`squirrel.base`¶

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

Bases: object

Database backed file selection (base class for Squirrel).

Parameters:	database (`Database` or `str`) – Database instance or file path to database. persistent (`str`) – If given a name, create a persistent selection.

A selection in this context represents the list of files to be made available to the application. Instead of using Selection directly, user applications should usually use its subclass Squirrel which adds content indices to the selection and provides high level data querying.

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.

Besides the filename references, desired content kind masks and file format indications are stored in the selection’s database table to make the user choice regarding these options persistent on a per-file basis. Book-keeping on whether files are unknown, known or if modification checks are forced is handled in the selection’s file-state table.

Paths of files can be added to the selection using the add() method and removed with remove(). undig_grouped() can be used to iterate over all content known to the selection.

get_database()[source]¶

Get the database to which this selection belongs.

Returns:	`Database` object

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

Add files to the selection.

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

remove(paths)[source]¶

Remove files from the selection.

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

iter_paths()[source]¶

Iterate over all file paths currently belonging to the selection.

Returns:	Iterator yielding file paths.

get_paths()[source]¶

Get all file paths currently belonging to the selection.

Returns:	List of file paths.

undig_grouped(skip_unchanged=False)[source]¶

Get inventory of cached content for all files in the selection.

Parameters:	skip_unchanged (bool) – 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 Nut objects representing the contents of the file.

flag_modified(check=True)[source]¶

Mark files which have been modified.

Parameters:	check (bool) – If `True` query modification times of known files on disk. If `False`, only flag unknown files.

Assumes file state is 0 for newly added files, 1 for files added again to the selection (forces check), or 2 for all others (no checking is done for those).

Sets file state to 0 for unknown or modified files, 2 for known and not modified files.

class SquirrelStats(**kwargs)[source]¶

Bases: pyrocko.guts.Object

Container to hold statistics about contents available from a Squirrel.

See also Squirrel.get_stats().

♦ nfiles¶

int

Number of files in selection.

♦ nnuts¶

int

Number of index nuts in selection.

♦ codes¶

list of tuple of str objects objects, default: []

Available code sequences in selection, e.g. (agency, network, station, location) for stations nuts.

♦ kinds¶

list of str objects, default: []

Available content types in selection.

♦ total_size¶

int

Aggregated file size of files is selection.

♦ counts¶

dict of dict of int objects objects, default: {}

Breakdown of how many nuts of any content type and code sequence are available in selection, counts[kind][codes].

♦ tmin¶

builtins.float (pyrocko.guts.Timestamp), optional

Earliest start time of all nuts in selection.

♦ tmax¶

builtins.float (pyrocko.guts.Timestamp), optional

Latest end time of all nuts in selection.

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:

Parameters:	env (`SquirrelEnvironment` or `str`) – Squirrel environment instance or directory path to use as starting point for its detection. By default, the current directory is used as starting point. When searching for a usable environment the directory `'.squirrel'` or `'squirrel'` in the current (or starting point) directory is used if it exists, otherwise the parent directories are search upwards for the existence of such a directory. If no such directory is found, the user’s global Squirrel environment `'$HOME/.pyrocko/squirrel'` is used. database (`Database` or `str`) – Database instance or path to database. By default the database found in the detected Squirrel environment is used. cache_path (`str`) – Directory path to use for data caching. By default, the `'cache'` directory in the detected Squirrel environment is used. persistent (`str`) – If given a name, create a persistent selection.

env (SquirrelEnvironment or str) – Squirrel environment instance or directory path to use as starting point for its detection. By default, the current directory is used as starting point. When searching for a usable environment the directory '.squirrel' or 'squirrel' in the current (or starting point) directory is used if it exists, otherwise the parent directories are search upwards for the existence of such a directory. If no such directory is found, the user’s global Squirrel environment '$HOME/.pyrocko/squirrel' is used.
database (Database or str) – Database instance or path to database. By default the database found in the detected Squirrel environment is used.
cache_path (str) – Directory path to use for data caching. By default, the 'cache' directory in the detected Squirrel environment is used.
persistent (str) – If given a name, create a persistent selection.

This is the central class of the Squirrel framework. It provides a unified interface to query and access seismic waveforms, station meta-data and event information from local file collections and remote data sources. For prompt responses, a profound database setup is used under the hood. To speed up assemblage of ad-hoc data selections, files are indexed on first use and the extracted meta-data is remembered in the database for subsequent accesses. Bulk data is lazily loaded from disk and remote sources, just when requested. Once loaded, data is cached in memory to expedite typical access patterns. Files and data sources can be dynamically added to and removed from the Squirrel selection at runtime.

Queries are restricted to the contents of the files currently added to the Squirrel selection (usually a subset of the information collected in the attached global file meta-information database). This list of files is referred to here as the “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 and are deleted when the database connection is closed or the application exits. To create a selection which is not deleted at exit, supply a name to the persistent argument of the Squirrel constructor. Persistent selections are shared among applications using the same database.

`Squirrel.add`(paths[, kinds, format, check, …])	Add files to the selection.
`Squirrel.add_virtual`(nuts[, virtual_paths])	Add content which is not backed by files.
`Squirrel.add_source`(source)	Add remote resource.
`Squirrel.add_fdsn`(args, *kwargs)	Add FDSN site for transparent remote data access.
`Squirrel.add_catalog`(args, *kwargs)	Add online catalog for transparent event data access.
`Squirrel.add_dataset`(path[, check, …])	Read dataset description from file and add its contents.
`Squirrel.update`([constraint])	Update or partially update channel and event inventories.
`Squirrel.update_waveform_promises`([constraint])	Permit downloading of remote waveforms.
`Squirrel.advance_accessor`(accessor[, cache])	Notify memory caches about consumer moving to a new data window.
`Squirrel.clear_accessor`(accessor[, cache])	Notify memory caches about a consumer having finished.
`Squirrel.reload`()	Check for modifications and reindex modified files.
`Squirrel.iter_nuts`([kind, tmin, tmax, …])	Iterate content entities matching given constraints.
`Squirrel.iter_kinds`([codes])	Iterate over content types available in selection.
`Squirrel.iter_deltats`([kind])	Iterate over sampling intervals available in selection.
`Squirrel.iter_codes`([kind])	Iterate over content identifier code sequences available in selection.
`Squirrel.iter_counts`([kind])	Iterate over number of occurrences of any (kind, codes) combination.
`Squirrel.get_nuts`(args, *kwargs)	Get content entities matching given constraints.
`Squirrel.get_time_span`([kinds])	Get time interval over all content in selection.
`Squirrel.get_deltat_span`(kind)	Get min and max sampling interval of all content of given kind.
`Squirrel.get_deltats`([kind])	Get sampling intervals available in selection.
`Squirrel.get_kinds`([codes])	Get content types available in selection.
`Squirrel.get_codes`([kind])	Get identifier code sequences available in selection.
`Squirrel.get_counts`([kind])	Get number of occurrences of any (kind, codes) combination.
`Squirrel.get_nfiles`()	Get number of files in selection.
`Squirrel.get_nnuts`()	Get number of nuts in selection.
`Squirrel.get_total_size`()	Get aggregated file size available in selection.
`Squirrel.get_stats`()	Get statistics on contents available through this selection.
`Squirrel.get_coverage`(kind[, tmin, tmax, …])	Get coverage information.
`Squirrel.get_content`(nut[, cache, accessor])	Get and possibly load full content for a given index entry from file.
`Squirrel.get_stations`([obj, tmin, tmax, …])	Get stations matching given constraints.
`Squirrel.get_pyrocko_stations`(args, *kwargs)
`Squirrel.get_channels`([obj, tmin, tmax, …])
`Squirrel.get_responses`([obj, tmin, tmax, …])
`Squirrel.get_events`([obj, tmin, tmax, time, …])
`Squirrel.get_waveform_nuts`([obj, tmin, …])
`Squirrel.get_waveforms_primitive`([obj, …])
`Squirrel.get_waveforms`([obj, tmin, tmax, …])
`Squirrel.chopper_waveforms`([obj, tmin, …])	Iterate window-wise over waveform data.
`Squirrel.pile`
`Squirrel.snuffle`()
`Squirrel.glob_codes`(kind, codes_list)	Find codes matching given patterns.
`Squirrel.print_tables`([table_names, stream])	Dump raw database tables in textual form (for debugging purposes).

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

Add files to the selection.

Parameters:

Parameters:	paths (`list` of `str`) – Iterator yielding paths to files or directories to be added to the selection. Recurses into directories. If given a `str`, it is treated as a single path to be added. kinds (`list` of `str`) – Content types to be made available through the Squirrel selection. By default, all known content types are accepted. format (`str`) – File format identifier or `'detect'` to enable auto-detection.

paths (list of str) – Iterator yielding paths to files or directories to be added to the selection. Recurses into directories. If given a str, it is treated as a single path to be added.
kinds (list of str) – Content types to be made available through the Squirrel selection. By default, all known content types are accepted.
format (str) – File format identifier or 'detect' to enable auto-detection.

Complexity: O(log N)

reload()[source]¶

Check for modifications and reindex modified files.

Based on file modification times.

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

Add content which is not backed by files.

Parameters:	nuts (iterator yielding `Nut` objects) – Content pieces to be added. virtual_paths (`list` of `str`) – List of virtual paths to prevent creating a temporary list of the nuts while aggregating the file paths for the selection.

Stores to the main database and the selection.

add_source(source)[source]¶

Add remote resource.

Parameters:	source (subclass of `Source`) – Remote data access client instance.

add_fdsn(*args, **kwargs)[source]¶

Add FDSN site for transparent remote data access.

Arguments are passed to FDSNSource.

add_catalog(*args, **kwargs)[source]¶

Add online catalog for transparent event data access.

Arguments are passed to CatalogSource.

add_dataset(path, check=True, progress_viewer='terminal')[source]¶

Read dataset description from file and add its contents.

Parameters:	path (str) – Path to dataset description file. See `dataset`. check (bool) – If `True` query modification times of known files on disk. If `False`, only flag unknown files.

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

Iterate content entities matching given constraints.

Parameters:

Parameters:	kind (`str`, `list` of `str`) – Content kind (or kinds) to extract. tmin (timestamp) – Start time of query interval. tmax (timestamp) – End time of query interval. codes (`tuple` of `str`) – Pattern of content codes to query. naiv (`bool`) – Bypass time span lookup through indices (slow, for testing). kind_codes_ids (`list` of `str`) – Kind-codes IDs of contents to be retrieved (internal use).

kind (str, list of str) – Content kind (or kinds) to extract.
tmin (timestamp) – Start time of query interval.
tmax (timestamp) – End time of query interval.
codes (tuple of str) – Pattern of content codes to query.
naiv (bool) – Bypass time span lookup through indices (slow, for testing).
kind_codes_ids (list of str) – Kind-codes IDs of contents to be retrieved (internal use).

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

Yields 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).

Time spans of content entities to be matched 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_nuts(*args, **kwargs)[source]¶

Get content entities matching given constraints.

Like iter_nuts() but returns results as a list.

get_time_span(kinds=None)[source]¶

Get time interval over all content in selection.

Complexity: O(1), independent of the number of nuts.

Returns:	(tmin, tmax)

get_deltat_span(kind)[source]¶

Get min and max sampling interval of all content of given kind.

Parameters:	kind (str) – Content kind
Returns:	(deltat_min, deltat_max)

iter_kinds(codes=None)[source]¶

Iterate over content types available in selection.

Parameters:	codes (`tuple` of `str`) – If given, get kinds only for selected codes identifier.