squirrel.client

class Source(**kwargs)

Bases: pyrocko.guts.Object

Base class for Squirrel data-sources.

Data-sources can be attached to a Squirrel instance to allow transparent access to remote (or otherwise generated) resources, e.g. through FDSN web services (FDSNSource) or online event catalogs (CatalogSource).

Derived classes implement the details of querying, caching, updating and bookkeeping of the accessed data.

update_channel_inventory(squirrel, constraint)

Let local inventory be up-to-date with remote for a given constraint.

update_event_inventory(squirrel, constraint)

Let local inventory be up-to-date with remote for a given constraint.

update_waveform_promises(squirrel, constraint)

Let local inventory be up-to-date with remote for a given constraint.

remove_waveform_promises(squirrel, from_database='selection')

Remove waveform promises from live selection or global database.

Parameters

from_database – Remove from live selection 'selection' or global database 'global'.

class Constraint(**kwargs)

Bases: pyrocko.guts.Object

Used by some data-sources to grow or join locally mirrored data selections.

Squirrel data-sources typically try to mirror only a subset of the remotely available data. This subset may need to be grown or updated when data from other time intervals or from locations outside the initially requested region is requested. This class helps in the involved bookeeping.

The current implementation only supports a time interval selection with a single time span but more sophisticated constraints, including e.g. location boxes could be thought of.

♦ tmin

time_float (pyrocko.guts.Timestamp), optional

♦ tmax

time_float (pyrocko.guts.Timestamp), optional

♦ codes

list of pyrocko.squirrel.model.CodesNSLCE objects, default: []

contains(constraint)

Check if the constraint completely includes a more restrictive one.

Parameters

constraint (Constraint) – Other constraint.

expand(constraint)

Widen constraint to include another given constraint.

Parameters

constraint (Constraint) – Other constraint.

Update is done in-place.

class FDSNSource(site, query_args=None, **kwargs)

Bases: pyrocko.squirrel.client.base.Source, pyrocko.has_paths.HasPaths

Squirrel data-source to transparently get data from FDSN web services.

Attaching an FDSNSource object to a Squirrel allows the latter to download station and waveform data from an FDSN web service should the data not already happen to be available locally.

♦ site

str

FDSN site url or alias name (see pyrocko.client.fdsn).

♦ query_args

dict of str objects, optional

Common query arguments, which are appended to all queries.

♦ expires

float (pyrocko.guts.Duration), optional

Expiration time [s]. Information older than this will be refreshed. This only applies to station-metadata. Waveforms do not expire. If set to None neither type of data expires.

♦ cache_path

str, optional

Directory path where any downloaded waveforms and station meta-data are to be kept. By default the Squirrel environment’s cache directory is used.

♦ shared_waveforms

bool, default: False

If True, waveforms are shared with other FDSN sources in the same Squirrel environment. If False, they are kept separate.

♦ user_credentials

tuple of 2 str objects, optional

User and password for FDSN servers requiring password authentication

♦ auth_token

str, optional

Authentication token to be presented to the FDSN server.

♦ auth_token_path

str, optional

Path to file containing the authentication token to be presented to the FDSN server.

♦ hotfix_module_path

str (pyrocko.has_paths.Path), optional

Path to Python module to locally patch metadata errors.

update_channel_inventory(squirrel, constraint=None)

Let local inventory be up-to-date with remote for a given constraint.

update_waveform_promises(squirrel, constraint)

Let local inventory be up-to-date with remote for a given constraint.

remove_waveform_promises(squirrel, from_database='selection')

Remove waveform promises from live selection or global database.

Parameters

from_database – Remove from live selection 'selection' or global database 'global'.

class CatalogSource(catalog, query_args=None, **kwargs)

Bases: pyrocko.squirrel.client.base.Source

Squirrel data-source to transparently access online earthquake catalogs.

The catalog source maintains and synchronizes a partial copy of the online catalog, e.g. of all events above a certain magnitude. The time span for which the local copy of the catalog should be up-to date is maintained automatically be Squirrel. Data is loaded and updated in chunks as needed in a just-in-time fashion. Data validity can optionally expire after a given period of time and new data can be treated to be preliminary. In both cases information will be refreshed as needed.

♦ catalog

str

Catalog name.

♦ query_args

dict of str objects, optional

Common arguments, which are appended to all queries, e.g. to constrain location, depth or magnitude ranges.

♦ expires

float (pyrocko.guts.Duration), optional

Expiration time [s]. Information older than this will be refreshed, i.e. queried again.

♦ anxious

float (pyrocko.guts.Duration), optional

Anxiety period [s]. Information will be treated as preliminary if it was younger than this at the time of its retrieval. Preliminary information is refreshed on each query relevant to it.

♦ cache_path

str, optional

Directory path where the partial local copy of the catalog is kept. By default the Squirrel environment’s cache directory is used.

update_event_inventory(squirrel, constraint=None)

Let local inventory be up-to-date with remote for a given constraint.

class FileFormat(...) → dummy for str

Bases: pyrocko.guts.StringChoice

Any str out of ['detect', 'datacube', 'mseed', 'pyrocko_events', 'pyrocko_stations', 'sac', 'stationxml', 'tdms_idas', 'virtual', 'yaml'].

class ContentKind(...) → dummy for str

Bases: pyrocko.guts.StringChoice

Any str out of ['waveform', 'station', 'channel', 'response', 'event'].

class LocalData(*args, **kwargs)

Bases: pyrocko.squirrel.client.base.Source, pyrocko.has_paths.HasPaths

A collection of local files attachable as a Squirrel data-source.

♦ paths

list of str (pyrocko.has_paths.Path) objects, default: []

Directory and file paths to add to the Squirrel instance. See Squirrel.add().

♦ kinds

list of str (ContentKind) objects, optional

Content kinds to be added to the Squirrel selection. By default all known content kinds are added.

♦ include

str, optional

If not None, files are only included if their paths match the given regular expression pattern.

♦ exclude

str, optional

If not None, files are only included if their paths do not match the given regular expression pattern.

♦ format

str (FileFormat), default: 'detect'

Assume files are of given format.