pyrocko.squirrel.model

Data model and content types handled by the Squirrel framework.

Squirrel uses flat content types to represent waveform, station, channel, response, event, and a few other objects. A common subset of the information in these objects is indexed in the database, currently: kind, codes, time interval and sampling rate. The Nut objects encapsulate this information together with information about where and how to get the associated bulk data.

Further content types are defined here to handle waveform orders, waveform promises, data coverage and sensor information.

Functions

codes_patterns_for_kind(kind_id, codes)	Convert codes patterns to a normalized list of query patterns.
get_default_earthmodel()	Get the default earth model for ray computations.
join_coverages(coverages[, tbleed])	Combine several coverages into one, merging their change points.
make_rich_coverage(kinds, coverages)	Combine several coverages of the same codes but different content kinds into one, encoding each kind's coverage state in separate bits of the combined changes counts.
tjoin(seconds, offset)	Join a full-seconds/fractional-offset pair back into a single time value (inverse of tsplit()).
to_codes(kind_id, obj)	Convert an object to a codes object of the class appropriate for a given content kind.
to_codes_guess(s)	Convert a dot-separated string to a codes object, guessing the appropriate codes class from its number of dots.
to_codes_simple(kind_id, codes_safe_str)	Convert a safe-string representation of codes to a codes object.
to_kind(kind_id)	Get content kind name for a content kind id.
to_kind_id(kind)	Get content kind id for a content kind name.
to_kind_ids(kinds)	Get content kind ids for a list of content kind names, see to_kind_id().
to_kinds(kind_ids)	Get content kind names for a list of content kind ids, see to_kind().
tsplit(t)	Split time into full-seconds and fractional-offset parts, for compact, fast-comparable database storage.

Classes

Channel(**kwargs)	A channel of a seismic station.
ChannelBase(**kwargs)	Base class for Channel and Sensor, providing the common properties of a single seismic recording channel or a group of channels forming a sensor.
Coverage(**kwargs)	Information about times covered by a waveform or other time series data.
DummyTrace(nut)	Lightweight, meta-information-only stand-in for a Trace, backed by a Nut.
Nut([file_path, file_format, file_mtime, ...])	Index entry referencing an elementary piece of content.
QuantityType(...)	Choice of observational or technical quantity.
Response(**kwargs)	The instrument response of a seismic station channel.
ResponseStage(**kwargs)	Representation of a response stage.
Sensor(**kwargs)	Representation of a channel group.
Station(**kwargs)	A seismic station.
WaveformOrder(**kwargs)	Waveform request information.
WaveformPromise(**kwargs)	Information about a waveform potentially downloadable from a remote site.

Exceptions

InvalidWaveform	Raised when a downloaded waveform fails validation, see WaveformOrder.validate().
ProjectionError	Raised when a sensor's components cannot be rotated to the requested coordinate system, e.g. because the source geometry is missing or the given arguments conflict.

to_codes_simple(kind_id, codes_safe_str)

Convert a safe-string representation of codes to a codes object.

Parameters:

• kind_id (int) – Content kind determining the target codes class, one of the ids given in g_content_kind_ids.

• codes_safe_str (str) – Codes as a database-safe string representation.

Return type:

Codes (subclass appropriate for kind_id)

to_codes(kind_id, obj)

Convert an object to a codes object of the class appropriate for a given content kind.

Parameters:

• kind_id (int) – Content kind determining the target codes class, one of the ids given in g_content_kind_ids.

• obj – Value to be converted, anything accepted by the target codes class’s constructor (e.g. a dot-separated string or a tuple).

Return type:

Codes (subclass appropriate for kind_id)

to_codes_guess(s)

Convert a dot-separated string to a codes object, guessing the appropriate codes class from its number of dots.

STA (no dots) gives CodesX, which matches the station code when used for channel or station queries, and the name for other content kinds. NET.STA gives CodesNSL with any location code.

Parameters:

s (str) – Dot-separated codes string, e.g. 'NET.STA.LOC.CHA'.

Return type:

Codes

Raises:

CodesError – If the number of dots does not match any known codes class.

codes_patterns_for_kind(kind_id, codes)

Convert codes patterns to a normalized list of query patterns.

Parameters:

• kind_id (int) – Content kind determining the target codes class, one of the ids given in g_content_kind_ids.

• codes (anything accepted by to_codes(), or list thereof) – Single codes pattern, or list thereof, in any form accepted by to_codes(). Already-normalized input (as returned by this function) is passed through unchanged.

Returns:

Normalized list of codes patterns, appropriate for the queried content kind. For station queries, an additional pattern matching any location code is added, since SEED/StationXML conventions treat the location code as part of the channel rather than the station, unlike CodesNSL (see its docstring).

Return type:

codes_patterns_list

to_kind(kind_id)

Get content kind name for a content kind id.

Parameters:

kind_id (int) – Content kind id, one of the ids given in g_content_kind_ids.

Return type:

str

to_kinds(kind_ids)

Get content kind names for a list of content kind ids, see to_kind().

to_kind_id(kind)

Get content kind id for a content kind name.

Parameters:

kind (str) – Content kind name, e.g. 'waveform', 'station', 'channel', 'response' or 'event'.

Return type:

int

to_kind_ids(kinds)

Get content kind ids for a list of content kind names, see to_kind_id().

tsplit(t)

Split time into full-seconds and fractional-offset parts, for compact, fast-comparable database storage.

Parameters:

t (get_time_float()) – Time to be split, or None.

Returns:

(seconds, offset), where seconds is the floored full seconds part and offset the remaining fractional part, in integer units of g_offset_time_unit seconds. Returns (None, 0) if t is None.

Return type:

tuple of (int or None, int)

tjoin(seconds, offset)

Join a full-seconds/fractional-offset pair back into a single time value (inverse of tsplit()).

Parameters:

• seconds (int) – Full seconds part, or None.

• offset (int) – Fractional part, in integer units of g_offset_time_unit seconds.

Returns:

Joined time, or None if seconds is None.

Return type:

get_time_float()

class Station(**kwargs)

Bases: Location

A seismic station.

♦ codes

pyrocko.model.codes.CodesNSL

Codes identifying the station (NET.STA.LOC).

♦ tmin

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

Start time of station epoch.

♦ tmax

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

End time of station epoch.

♦ description

str, optional

Additional description of the station.

property time_span

Get station’s epoch as (tmin, tmax) tuple.

get_pyrocko_station()

Get station as a classic Pyrocko station object.

Returns:

Converted station object.

Return type:

pyrocko.model.station.Station

class ChannelBase(**kwargs)

Bases: Location

Base class for Channel and Sensor, providing the common properties of a single seismic recording channel or a group of channels forming a sensor.

♦ codes

pyrocko.model.codes.CodesNSLCE

Codes identifying the channel (NET.STA.LOC.CHA.EXTRA).

♦ tmin

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

Start time of channel epoch.

♦ tmax

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

End time of channel epoch.

♦ deltat

float, optional

Sampling interval [s].

property time_span

Get channel’s epoch as (tmin, tmax) tuple.

overlaps(tmin, tmax)

Check if channel’s epoch overlaps with a given time span.

Parameters:

• tmin (get_time_float()) – Start time of query interval.

• tmax (get_time_float()) – End time of query interval.

Returns:

True if the channel’s epoch (tmin, tmax) has any overlap with the given interval.

Return type:

bool

class Channel(**kwargs)

Bases: ChannelBase

A channel of a seismic station.

♦ dip

float, optional

Dip angle of channel [deg], -90 is up, 0 is horizontal, 90 is down.

♦ azimuth

float, optional

Azimuth angle of channel [deg], 0 is north, 90 is east.

get_pyrocko_channel()

Get channel as a classic Pyrocko channel object.

Returns:

Converted channel object.

Return type:

pyrocko.model.station.Channel

property orientation_enz

Get sensor orientation as unit vector in East-North-Up coordinates, or None if azimuth or dip are not set.

exception ProjectionError

Bases: Exception

Raised when a sensor’s components cannot be rotated to the requested coordinate system, e.g. because the source geometry is missing or the given arguments conflict.

get_default_earthmodel()

Get the default earth model for ray computations.

The model is pyrocko.cake.load_model()’s default, loaded once and cached.

Return type:

pyrocko.cake.LayeredModel

class Sensor(**kwargs)

Bases: ChannelBase

Representation of a channel group.

♦ channels

list of Channel objects, default: []

Channels forming this sensor, e.g. the three components of a three-component seismometer.

classmethod from_channels(channels)

Group channels into sensors.

Parameters:

channels (iterable of Channel objects) – Channels to be grouped.

Returns:

Sensors formed by grouping the given channels by matching station/location codes, orientation-independent channel code (i.e. NET.STA.LOC.BI, where B and I are the SEED band and instrument codes, e.g. 'HH', omitting the component character) and time span, splitting groups where the individual channels’ time spans don’t fully align.

Return type:

list of Sensor objects

channel_vectors()

Get orientation unit vectors of member channels.

Returns:

Orientation vectors of the member channels in East-North-Up coordinates, stacked into a (nchannels, 3) array, in the order of channels.

Return type:

numpy.ndarray

projected_channels(system, component_names)

Get synthetic channel definitions for a given target coordinate system.

Parameters:

• system (numpy.ndarray) – Target coordinate system as a (3, 3) rotation matrix, rows giving the new component directions in East-North-Up coordinates.

• component_names (str or list of str) – Component codes to be used for the three output channels, e.g. 'ENZ'.

Returns:

Synthetic channel definitions for the projected components.

Return type:

list of Channel objects

matrix_to(system, epsilon=1e-07)

Get rotation matrix from member channels to a given coordinate system.

Parameters:

• system (numpy.ndarray) – Target coordinate system as a (3, 3) rotation matrix, rows giving the new component directions in East-North-Up coordinates.

• epsilon (float) – Absolute values below this threshold are set to zero in the returned matrix, to clean up numerical noise.

Returns:

Rotation matrix mapping from the member channels’ orientations to the given target system.

Return type:

numpy.ndarray

projection_to(system, component_names)

Get projection to a given coordinate system.

Parameters:

• system (numpy.ndarray) – Target coordinate system as a (3, 3) rotation matrix, rows giving the new component directions in East-North-Up coordinates.

• component_names (str or list of str) – Component codes to be used for the three output channels, e.g. 'ENZ'.

Returns:

A tuple (matrix, in_channels, out_channels) as expected by pyrocko.trace.project().

Return type:

tuple

projection_to_enz()

Get projection to East-North-Up coordinates.

Returns:

A tuple (matrix, in_channels, out_channels) as expected by pyrocko.trace.project().

Return type:

tuple

projection_to_trz(source, azimuth=None, backazimuth=None)

Get projection to Transverse-Radial-Up coordinates.

Parameters:

• source (Location) – Source location to compute the backazimuth from, or None if backazimuth or azimuth is given directly.

• azimuth (float) – Direction of propagation at the sensor [deg], i.e. backazimuth + 180, overriding the automatic computation from source.

• backazimuth (float) – Backazimuth [deg], i.e. direction from the sensor towards the source, overriding the automatic computation from source.

Returns:

A tuple (matrix, in_channels, out_channels) as expected by pyrocko.trace.project().

Return type:

tuple

incidence_angle(source=None, earthmodel=None, phases=None, distance=None, source_depth=None)

Get the incidence angle of a ray from a source at the sensor.

Parameters:

• source (Location) – Source location, used for the distance and source depth if these are not given directly.

• earthmodel (pyrocko.cake.LayeredModel) – Earth model. Default: see get_default_earthmodel().

• phases (list of pyrocko.cake.PhaseDef) – Candidate phases, the first arrival is used. Default: p and P.

• distance (float) – Source-sensor distance [deg].

• source_depth (float) – Source depth [m].

Returns:

Incidence angle [deg], as given by pyrocko.cake.Ray.incidence_angle().

Return type:

float

Raises:

ProjectionError if the geometry is incomplete or no ray connects source and sensor.

projection_to_lqt(source=None, earthmodel=None, phases=None, distance=None, source_depth=None, backazimuth=None, incidence=None)

Get projection to Longitudinal-Transverse-SH (ray-based) coordinates, after Plesinger et al. (1986).

Parameters:

• source (Location) – Source location to compute backazimuth and incidence angle from, or None if these are given directly.

• earthmodel – Earth model for the incidence angle computation, see incidence_angle().

• phases – Candidate phases for the incidence angle computation, see incidence_angle().

• distance – Source-sensor distance [deg], see incidence_angle().

• source_depth – Source depth [m], see incidence_angle().

• backazimuth (float) – Backazimuth [deg], i.e. direction from the sensor towards the source, overriding the automatic computation from source.

• incidence (float) – Incidence angle [deg], measured from vertical, overriding the automatic computation.

Returns:

A tuple (matrix, in_channels, out_channels) as expected by pyrocko.trace.project().

Return type:

tuple

project_to_enz(traces)

Rotate traces to East-North-Up coordinates.

Parameters:

traces (list of Trace objects) – Traces to be rotated, matching this sensor’s member channels.

Returns:

Rotated traces.

Return type:

list of Trace objects

project_to_trz(source, traces, azimuth=None, backazimuth=None)

Rotate traces to Transverse-Radial-Up coordinates.

Parameters:

• source (Location) – Source location to compute the backazimuth from, or None if backazimuth or azimuth is given directly.

• traces (list of Trace objects) – Traces to be rotated, matching this sensor’s member channels.

• azimuth (float) – Direction of propagation at the sensor [deg], see projection_to_trz().

• backazimuth (float) – Backazimuth [deg], see projection_to_trz().

Returns:

Rotated traces.

Return type:

list of Trace objects

project_to_lqt(source, traces, earthmodel=None, phases=None, distance=None, source_depth=None, backazimuth=None, incidence=None)

Rotate traces to Longitudinal-Transverse-SH (ray-based) coordinates, see projection_to_lqt().

Parameters:

traces (list of Trace objects) – Traces to be rotated, matching this sensor’s member channels.

Other parameters as for projection_to_lqt().

Returns:

Rotated traces.

Return type:

list of Trace objects

class QuantityType(...) → str

Bases: StringChoice

Choice of observational or technical quantity.

SI units are used for all quantities, where applicable.

class ResponseStage(**kwargs)

Bases: Object

Representation of a response stage.

Components of a seismic recording system are represented as a sequence of response stages, e.g. sensor, pre-amplifier, digitizer, digital downsampling.

♦ input_quantity

str (QuantityType), optional

Physical quantity accepted at input of stage.

♦ input_sample_rate

float, optional

Sampling rate at input of stage [Hz].

♦ output_quantity

str (QuantityType), optional

Physical quantity produced at output of stage.

♦ output_sample_rate

float, optional

Sampling rate at output of stage [Hz].

♦ elements

list of pyrocko.response.FrequencyResponse objects, default: []

Sequence of frequency responses combined (multiplied) to form this stage.

♦ log

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

Log messages noting problems encountered or simplifications made while converting response information from its source format, with entries of the form (level, context, message).

property stage_type

Attempt to classify the stage as 'sensor', 'electronics', 'digitizer', 'decimation', 'conversion', 'combination' or 'unknown', based on its input/output quantities and decimation factor.

property decimation_factor

Get decimation factor of stage, or None if it cannot be determined from input_sample_rate and output_sample_rate.

property summary_quantities

One-line summary of input/output quantities.

property summary_rates

One-line summary of input/output sampling rates.

property summary_elements

One-line summary of the combined elements.

property summary_log

One-letter-per-entry summary of log severities.

property summary_entries

Get tuple of one-line summary values, for use with fmt_summary().

property summary

One-line summary of the response stage.

get_effective()

Get effective frequency response of this stage.

Returns:

Combined response of all elements.

Return type:

MultiplyResponse

class Response(**kwargs)

Bases: Object

The instrument response of a seismic station channel.

♦ codes

pyrocko.model.codes.CodesNSLCE

Codes identifying the channel (NET.STA.LOC.CHA.EXTRA) this response applies to.

♦ tmin

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

Start time of response epoch.

♦ tmax

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

End time of response epoch.

♦ stages

list of ResponseStage objects, default: []

Sequence of response stages, from sensor to digitizer output.

♦ checkpoints

list of pyrocko.response.FrequencyResponseCheckpoint objects, default: []

Gain checkpoints to be honoured, e.g. from a dataless SEED volume or a StationXML file, used to sanity-check the combined response computed from stages.

♦ deltat

float, optional

Sampling interval at output of response [s].

♦ log

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

Log messages noting problems encountered or simplifications made while converting response information from its source format, with entries of the form (level, context, message).

property time_span

Get response’s epoch as (tmin, tmax) tuple.

property nstages

Number of response stages.

property input_quantity

Physical quantity accepted at input of first stage, or None if no stages are present.

property output_quantity

Physical quantity produced at output of last stage, or None if no stages are present.

property output_sample_rate

Sampling rate at output of last stage [Hz], or None if no stages are present.

property summary_stages

One-line summary of the stages’ types.

property summary_quantities

One-line summary of input/output quantities and output sample rate.

property summary_log

One-letter-per-entry summary of log severities.

property summary_entries

Get tuple of one-line summary values, for use with fmt_summary().

property summary

One-line summary of the response.

get_effective(input_quantity=None, stages=(None, None), mode='complete', gain_frequency=None)

Get effective combined frequency response.

Parameters:

• input_quantity (str) – If given, prepend a conversion from the given physical quantity to the response’s native input_quantity.

• stages (tuple of 2 int or None) – Restrict combination to a sub-range of stages, given as (start, stop) index tuple, following Python slicing conventions. Use None for an open end.

• mode (str) – 'complete' to combine all selected stages, or 'sensor' to instead replace non-sensor stages with a constant gain evaluated at gain_frequency (useful to inspect the sensor’s response in isolation while still accounting for the overall system gain).

• gain_frequency (float) – Frequency [Hz] at which to evaluate the constant gain used to replace non-sensor stages when mode='sensor'. Required in that case.

Returns:

Combined response.

Return type:

MultiplyResponse

Results are cached per (input_quantity, stages) combination.

class WaveformPromise(**kwargs)

Bases: Object

Information about a waveform potentially downloadable from a remote site.

In the Squirrel framework, waveform promises are used to permit download of selected waveforms from a remote site. They are typically generated by calls to update_waveform_promises(). Waveform promises are inserted and indexed in the database similar to normal waveforms. When processing a waveform query, e.g. from get_waveforms(), and no local waveform is available for the queried time span, a matching promise can be resolved, i.e. an attempt is made to download the waveform from the remote site. The promise is removed after the download attempt (except when a network error occurs). This prevents Squirrel from making unnecessary queries for waveforms missing at the remote site.

♦ codes

pyrocko.model.codes.CodesNSLCE

Codes identifying the channel (NET.STA.LOC.CHA.EXTRA) of the promised waveform.

♦ tmin

pyrocko.util.get_time_float (pyrocko.guts.Timestamp)

Start time of promised waveform.

♦ tmax

pyrocko.util.get_time_float (pyrocko.guts.Timestamp)

End time of promised waveform.

♦ deltat

float, optional

Sampling interval of promised waveform [s].

♦ source_hash

str

Hash identifying the remote source client providing this promise.

property time_span

Get promise’s temporal span as (tmin, tmax) tuple.

exception InvalidWaveform

Bases: Exception

Raised when a downloaded waveform fails validation, see WaveformOrder.validate().

class WaveformOrder(**kwargs)

Bases: Object

Waveform request information.

♦ source_id

str

Id of remote source client to query, of the form 'client:<client-type>:<hash>', e.g. 'client:fdsn:<hash>'.

♦ codes

pyrocko.model.codes.CodesNSLCE

Codes identifying the channel (NET.STA.LOC.CHA.EXTRA) to be downloaded.

♦ deltat

float

Expected sampling interval of the waveform to be downloaded [s].

♦ tmin

pyrocko.util.get_time_float (pyrocko.guts.Timestamp)

Start time of waveform to be downloaded.

♦ tmax

pyrocko.util.get_time_float (pyrocko.guts.Timestamp)

End time of waveform to be downloaded.

♦ gaps

list of tuple of 2 pyrocko.util.get_time_float (pyrocko.guts.Timestamp) objects objects, default: []

List of (tmin, tmax) time spans already locally available, to be excluded from the request when possible.

♦ time_created

pyrocko.util.get_time_float (pyrocko.guts.Timestamp)

Time at which the order was created.

♦ anxious

float (pyrocko.guts.Duration), default: 600.0

Time span [s] before tmax within which the order is still considered to concern near-real-time data, see is_near_real_time().

property client

Get remote source client type (e.g. 'fdsn'), parsed from source_id.

key1()

Get key identifying the order, including its source, for duplicate/repeat-order detection.

key2()

Get key identifying the order, without its source, e.g. for cross-client bookkeeping of already-satisfied requests.

describe(site='?')

Get one-line description of the order.

Parameters:

site (str) – Name of remote site, for display purposes.

Return type:

str

validate(tr)

Check that a downloaded trace matches this order.

Parameters:

tr (Trace) – Downloaded waveform to be checked.

Raises:

InvalidWaveform – If the trace has no data samples, a sampling interval not matching deltat, or non-finite data values.

estimate_nsamples()

Estimate number of samples expected for the ordered time span.

is_near_real_time()

Check if order’s end time is close enough to its creation time to be considered a near-real-time request (see anxious).

class Nut(file_path=None, file_format=None, file_mtime=None, file_size=None, file_segment=None, file_element=None, kind_id=0, codes=('',), tmin_seconds=None, tmin_offset=0, tmax_seconds=None, tmax_offset=0, deltat=None, content=None, raw_content=None, tmin=None, tmax=None, values_nocheck=None)

Bases: Object

Index entry referencing an elementary piece of content.

So-called nuts are used in Pyrocko’s Squirrel framework to hold common meta-information about individual pieces of waveforms, stations, channels, etc. together with the information where it was found or generated.

♦ file_path

str, optional

Path of file containing the referenced content.

♦ file_format

str, optional

Content type of file, as used by the Squirrel IO backends (e.g. 'mseed', 'stationxml', 'yaml').

♦ file_mtime

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

Modification time of file, for change detection.

♦ file_size

int, optional

Size of file [bytes], for change detection.

♦ file_segment

int, optional

Index of segment within file, for file formats where a single file can contain multiple segments.

♦ file_element

int, optional

Index of content element within its segment, for content types where a segment may hold more than one element.

♦ kind_id

int

Content type, one of the ids given in g_content_kind_ids.

♦ codes

pyrocko.model.codes.Codes

Codes identifying the content, of a subclass appropriate for the given content kind.

♦ tmin_seconds

int, default: 0

Full seconds part of start time of content, needed for fast database queries.

♦ tmin_offset

int, optional, default: 0

Fractional/high-precision part of start time of content (see tsplit()).

♦ tmax_seconds

int, default: 0

Full seconds part of end time of content, needed for fast database queries.

♦ tmax_offset

int, optional, default: 0

Fractional/high-precision part of end time of content (see tsplit()).

♦ deltat

float, default: 0.0

Sampling interval of content, if applicable, else 0.0 [s].

♦ content

pyrocko.guts.Any, optional

The actual content object represented by this nut, if attached.

♦ raw_content

dict of pyrocko.guts.Any objects, default: {}

Additional, backend-specific raw content, keyed by content kind.

hash()

Compute hash from key, identifying this nut’s file origin.

Return type:

str

get_io_backend()

Get the Squirrel IO backend module responsible for file_format.

file_modified()

Check if the referenced file appears to have changed since indexing, by comparing current vs. indexed modification time and size.

Return type:

bool

property dkey

Get key used to index this nut in the database’s content table, as (kind_id, tmin_seconds, tmin_offset, codes).

property key

Get key identifying this nut’s file origin, as (file_path, file_segment, file_element, file_mtime).

property equality_values

Get values determining content equality (used by __eq__), as (file_segment, file_element, kind_id, codes, tmin_seconds, tmin_offset, tmax_seconds, tmax_offset, deltat).

diff(other)

Get list of differing equality_values fields between this and another nut.

Parameters:

other (Nut) – Nut to compare against.

Returns:

(field_name, this_value, other_value) tuples for each differing field.

Return type:

list of tuple

property tmin

Start time of content, joined from tmin_seconds/ tmin_offset (see tjoin()). Settable, splitting into those two fields (see tsplit()).

property tmax

End time of content, joined from tmax_seconds/ tmax_offset (see tjoin()). Settable, splitting into those two fields (see tsplit()).

property kscale

Time-block granularity index for this nut’s time span, used for indexing content at multiple scales (see tscale_edges and iter_nuts()’s tscale_min parameter).

property waveform_promise_kwargs

Get keyword arguments usable to create a WaveformPromise from this nut’s meta-information.

property station_kwargs

Get keyword arguments usable to create a Station from this nut’s meta-information.

property channel_kwargs

Get keyword arguments usable to create a Channel from this nut’s meta-information.

property response_kwargs

Get keyword arguments usable to create a Response from this nut’s meta-information.

property event_kwargs

Get keyword arguments usable to create a Event from this nut’s meta-information.

property trace_kwargs

Get keyword arguments usable to create a Trace matching this nut’s meta- information.

Trace’s tmax is the time of the last sample while Nut’s tmax is one delta more to simplify continuity checks.

property dummy_trace

Get a lightweight, meta-information-only stand-in for a Trace.

Return type:

DummyTrace

property summary_entries

Get tuple of one-line summary values, for use with fmt_summary().

property summary

One-line summary of the nut.

class DummyTrace(nut)

Bases: object

Lightweight, meta-information-only stand-in for a Trace, backed by a Nut.

Exposes the subset of Trace’s interface (tmin, tmax, deltat, network/station/location/ channel/extra, nslc_id, overlaps()) needed where a trace-like object is expected but no waveform data has been loaded, see Nut.dummy_trace.

overlaps(tmin, tmax)

Check if the represented nut’s time span overlaps with a given time span.

Parameters:

• tmin (get_time_float()) – Start time of query interval.

• tmax (get_time_float()) – End time of query interval.

Return type:

bool

class Coverage(**kwargs)

Bases: Object

Information about times covered by a waveform or other time series data.

♦ kind_id

int, optional

Content type.

♦ pattern

pyrocko.model.codes.Codes, optional

The codes pattern in the request, which caused this entry to match.

♦ codes

pyrocko.model.codes.Codes, optional

NSLCE or NSL codes identifier of the time series.

♦ deltat

float, optional

Sampling interval [s]

♦ tmin

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

Global start time of time series.

♦ tmax

pyrocko.util.get_time_float (pyrocko.guts.Timestamp), optional

Global end time of time series.

♦ changes

list of tuple of 2 pyrocko.guts.Any objects objects, optional

List of change points, with entries of the form (time, count), where a count of zero indicates start of a gap, a value of 1 start of normal data coverage and a higher value duplicate or redundant data coverage.

classmethod from_values(args)

Create coverage object from a (pattern, codes, deltat, tmin, tmax, changes, kind_id) tuple (internal use).

property summary_entries

Get tuple of one-line summary values, for use with fmt_summary().

property summary

One-line summary of the coverage.

property sample_rate

Sampling rate [Hz], derived from deltat, or None if unset.

property labels

Get (codes, sample_rate) tuple of display labels, e.g. for use as plot annotations.

property total

Total duration [s] covered by normal (non-gap) data, or None if changes is unset.

iter_spans()

Iterate over covered time spans.

Yields:

(tmin, tmax, count) tuples, where count is the number of overlapping/redundant data pieces covering the span (1 for normal coverage, higher for duplicate/redundant data).

iter_uncovered_by(other)

Iterate over time spans covered here but not in another coverage.

Parameters:

other (Coverage) – Coverage to compare against.

Yields:

(tmin, tmax, ia, ib) tuples, where ia/ib are the indices into this/the other coverage’s changes at the start of the yielded span.

iter_uncovered_by_combined(other)

Like iter_uncovered_by(), but merging adjacent spans belonging to the same gap in other.

Parameters:

other (Coverage) – Coverage to compare against.

Yields:

(tmin, tmax) tuples.

changes_as_arrays()

Get changes as a pair of NumPy arrays.

Returns:

(times, counts), or (None, None) if changes is unset.

Return type:

tuple of 2 numpy.ndarray

contiguous(tmin, tmax)

Get coverage count for a time span, if constant throughout.

Parameters:

• tmin (get_time_float()) – Start of time span to check.

• tmax (get_time_float()) – End of time span to check.

Returns:

The coverage count if it is constant across [tmin, tmax], or -1 if it changes within the span or is unknown.

Return type:

int

get(time)

Get coverage count at a given time instant.

Parameters:

time (get_time_float()) – Time instant to query.

Return type:

int

join_coverages(coverages, tbleed=0.0)

Combine several coverages into one, merging their change points.

Parameters:

• coverages (iterable of Coverage objects) – Coverages to be combined, e.g. of several channels belonging to the same sensor, for which overall combined data availability is of interest.

• tbleed (float) – Time interval to be removed at coverage edges and gaps [s]. This can be used, e.g. to track edge effect propagation through processing steps.

Returns:

Combined coverage. Its kind_id/ deltat are set only if all input coverages agree on them, else left unset (None); its pattern/codes are always left unset.

Return type:

Coverage

Raises:

pyrocko.trace.NoData – If coverages is empty, or the combined time span is empty.

make_rich_coverage(kinds, coverages)

Combine several coverages of the same codes but different content kinds into one, encoding each kind’s coverage state in separate bits of the combined changes counts.

Parameters:

• kinds (list of str) – Content kinds to encode, in the order their coverage states are packed into the combined counts (2 bits per kind, low bit first, see get_rich_coverage() for the kinds and their order used there).

• coverages (iterable of Coverage objects) – Coverages to be combined, all sharing the same codes, of the content kinds given in kinds (any kind may be represented multiple times, or not at all).

Returns:

Combined coverage with kind_id=None and each change point’s count encoding, per kind, 0 for no coverage, 1 for normal coverage, 2 for duplicate/redundant coverage or 3 if the coverage state could not be determined (see changes).

Return type:

Coverage