`squirrel`¶

Prompt seismological data access with a fluffy tail.

Usage¶

from pyrocko import squirrel as psq

sq = psq.Squirrel()
sq.add(files)

Concepts¶

squirrel
nut
database

Reference¶

class Selection(database, persistent=None)[source]¶

Bases: object

Database backed file selection.

Parameters:	database – `Database` object or path to database persistent (str) – if given a name, create a persistent selection

By default, a temporary table in the database is created to hold the names of the files in the selection. This table is only visible inside the application which created it. If a name is given to persistent, a named selection is created, which is visible also in other applications using the same database. Paths of files can be added to the selection using the add() method.

get_database()[source]¶

Get the database to which this selection belongs.

Returns:	`Database` object

silent_touch(file_path)[source]¶

Update modification time of file without initiating reindexing.

Useful to prolong validity period of data with expiration date.

add(file_paths, kind_mask=255, format='detect')[source]¶

Add files to the selection.

Parameters:	file_paths (iterator yielding `str` objects) – Paths to files to be added to the selection.

remove(file_paths)[source]¶

Remove files from the selection.

Parameters:	file_paths (`list` of `str`) – Paths to files to be removed from the selection.

undig_grouped(skip_unchanged=False)[source]¶

Get content inventory of all files in selection.

Param:	skip_unchanged: if `True` only inventory of modified files is yielded (`_flag_modified()` must be called beforehand).

This generator yields tuples ((format, path), nuts) where path is the path to the file, format is the format assignation or 'detect' and nuts is a list of pyrocko.squirrel.Nut objects representing the contents of the file.

class Squirrel(env=None, database=None, cache_path=None, persistent=None)[source]¶

Bases: pyrocko.squirrel.base.Selection

Prompt, lazy, indexing, caching, dynamic seismological dataset access.

Parameters:	database – `Database` object or path to database persistent (str) – if given a name, create a persistent selection

By default, temporary tables are created in the attached database to hold the names of the files in the selection as well as various indices and counters. These tables are only visible inside the application which created it. If a name is given to persistent, a named selection is created, which is visible also in other applications using the same database. Paths of files can be added to the selection using the add() method.

add(file_paths, kinds=None, format='detect', check=True)[source]¶

Add files to the selection.

Parameters:	file_paths – iterator yielding paths to files or directories to be added to the selection. Recurses into directories given. If given a str, it is treated as a single path to be added. kinds (`list` of `str`) – if given, allowed content types to be made available through the squirrel selection. format (str) – file format identifier or `'detect'` for auto-detection

Complexity: O(log N)

add_virtual(nuts, virtual_file_paths=None)[source]¶

Add content which is not backed by files.

Stores to the main database and the selection.

If virtual_file_paths are given, this prevents creating a temp list of the nuts while aggregating the file paths for the selection.

add_source(source)[source]¶: Add remote resource.

add_fdsn(*args, **kwargs)[source]¶: Add FDSN site for transparent remote data access.

add_catalog(*args, **kwargs)[source]¶: Add online catalog for transparent event data access.

iter_nuts(kind=None, tmin=None, tmax=None, codes=None, naiv=False, kind_codes_ids=None)[source]¶

Iterate content matching given contraints.

Parameters:	kind – `str`, content kind to extract or sequence of such tmin – timestamp, start time of interval tmax – timestamp, end time of interval codes – tuple of str, pattern of content codes to be matched

Complexity: O(log N) for the time selection part due to heavy use of database indexes.

Yields pyrocko.squirrel.Nut objects representing the intersecting content.

Query time span is treated as a half-open interval [tmin, tmax). However, if tmin equals tmax, the edge logics are modified to closed-interval so that content intersecting with the time instant t = tmin = tmax is returned (otherwise nothing would be returned as [t, t) never matches anything).

Content time spans are also treated as half open intervals, e.g. content span [0, 1) is matched by query span [0, 1) but not by [-1, 0) or [1, 2). Also here, logics are modified to closed-interval when the content time span is an empty interval, i.e. to indicate a time instant. E.g. time instant 0 is matched by [0, 1) but not by [-1, 0) or [1, 2).

get_time_span()[source]¶

Get time interval over all content in selection.

Complexity O(1), independent of number of nuts

Returns:	(tmin, tmax)

get_deltat_span(kind)[source]¶

Get min and max sampling interval of all waveform contents.

Returns:	(deltat_min, deltat_max)

iter_kinds(codes=None)[source]¶

Iterate over content types available in selection.

Parameters:	codes – if given, get kinds only for selected codes identifier