pyrocko.squirrel.operators.base¶

On-demand, chainable data-processing operators.

An Operator (via its base class BaseOperator) presents the same query interface as Squirrel (get_waveforms, get_channels, get_responses, get_carpets, get_sensors, chopper_waveforms, chopper_carpets, get_coverage, etc.), but derives its content lazily, on each call, from one or more input objects, which may themselves be a Squirrel or another operator. This makes operators chainable/stackable: connecting a sequence of operators (typically declared as a Mantra) forms an on-demand processing pipeline that can be queried exactly like a squirrel, with each stage transforming what it receives from its input before handing it to its consumer. No processing happens until content is actually requested; nothing is precomputed or cached to disk by the operator itself.

Each operator advertises which content kinds it needs from its input via BaseOperator.kind_requires and which it offers to its consumer via BaseOperator.kind_provides. Which codes (channel/sensor identifiers) it can produce, and from which input codes each is derived, is tracked in a codes mapping (CodesMapping), kept up to date against the input’s currently available codes via BaseOperator.update_mappings(). For the common case handled by Operator, that mapping is driven by a codes_projection (CodesProjection): input codes are grouped by a template key and projected to new output codes via a second template, with {i.*}/{o.*} placeholders referring to the input codes’ attributes and the producing Outlet’s attributes, respectively (e.g. Restitution appends R{o.quantity} to derive its output channel codes).

The actual content transformation for a given content kind is implemented by overriding the corresponding process_* method (e.g. BaseOperator.process_waveforms()); BaseOperator’s own implementations mostly pass content through unchanged, appropriate for operators which only rename/reproject codes.

An operator may have more than one input (fan-in), transparently combined via InputCombinator; which operators feed which is normally set up declaratively through a Mantra’s setup(), using operators’ input_names, rather than by calling BaseOperator.add_input() directly.

Functions

`basic_codes_projection_t`(template)	Get a Guts field definition for a `Operator.codes_projection` attribute, defaulting to a `CodesProjection` with a given template.
`by_codes`(xs)	Group objects with a `codes` attribute by their codes.
`by_codes_unique`(xs)	Like `by_codes()`, but keeping only codes with exactly one matching object, unwrapped from their single-element list.
`new_operator_id`()	Generate a fresh unique id for an operator instance (see `BaseOperator.reset()`).
`scodes`(codes)	Get compact textual summary of a group of codes, for display purposes.
`time_min_max`(codes_to_traces)	Get overall time span of a codes-to-traces mapping.

Classes

`BaseOperator`(**kwargs)	Base class for on-demand data-processing operators.
`CarpetHOverV`(**kwargs)	Combine horizontal (N/E) and vertical (Z) component carpets into a single horizontal-to-vertical ratio carpet, per sensor.
`CarpetSum`(**kwargs)	Sum (or average) all input carpets into a single combined carpet.
`CodesFilter`(**kwargs)	Filter by codes patterns.
`CodesFilterBase`(**kwargs)	Base class for codes filters, used to select which of an operator's input codes it should act on (see `BaseOperator.update_mappings()`).
`CodesMapping`()	Records which output codes an operator derives from which input codes, for a single output group (internal use, see `BaseOperator.iter_mappings()`).
`CodesProjection`([template, group_by])	Template-string-based codes projection.
`CodesProjectionBase`(**kwargs)	Base class for codes projections: combined filter, grouping and codes-derivation strategies used by `Operator` (see `Operator.codes_projection`).
`InputCombinator`(inputs)	Transparently fans out queries to several inputs and aggregates the results, giving a combined input the same interface as a single operator/squirrel input (internal use, see `BaseOperator.add_input()`).
`Operator`(**kwargs)	Base class for operators with typical filter-group-translate behaviour.
`Outlet`(**kwargs)	Describes one distinct output "channel" of an operator, e.g. one component of a 3-component coordinate transform.
`Restitution`(**kwargs)	Removes the instrument response, restituting to a chosen physical quantity.
`ToENZ`(**kwargs)	Rotate sensors to East-North-Up components.
`ToLQT`(**kwargs)	Rotate sensors to Longitudinal-Transverse-SH (ray-based) components, relative to a source and earth model.
`ToTRZ`(**kwargs)	Rotate sensors to Transverse-Radial-Up components, relative to a source or a fixed backazimuth.
`Transform`(**kwargs)	Base class for coordinate-system transforms (see `ToENZ`, `ToTRZ`, `ToLQT`), rotating each group of matching channels (via `project_to_enz()`-alike sensor projections) into a new component system.

Exceptions

OperatorError

Raised on operator setup/wiring errors, e.g. incompatible input (see BaseOperator.add_input()) or an unsupported multi-squirrel setup (see InputCombinator.get_squirrel()).

ichain(iterable, /)¶: Alternative chain() constructor taking a single iterable argument that evaluates lazily.

exception OperatorError[source]¶

Bases: SquirrelError

Raised on operator setup/wiring errors, e.g. incompatible input (see BaseOperator.add_input()) or an unsupported multi-squirrel setup (see InputCombinator.get_squirrel()).

scodes(codes)[source]¶

Get compact textual summary of a group of codes, for display purposes.

Parameters:: codes (iterable of Codes objects, all of the same class) – Codes to be summarized.
Returns:: If all but one code element (e.g. network, station, …) agree across codes, a single dot-separated string with the differing element rendered as a comma-separated {...} group (e.g. 'NET.STA..{HHE,HHN,HHZ}.'). Otherwise, the codes listed out individually, comma-separated.
Return type:: str

time_min_max(codes_to_traces)[source]¶

Get overall time span of a codes-to-traces mapping.

Parameters:: codes_to_traces (dict of list of Trace) – Traces to inspect, keyed by codes (only the values are used).
Returns:: (tmin, tmax), the earliest start and latest end time across all traces.
Return type:: tuple

by_codes(xs: HasCodes) → dict[CodesNSLCE, List[HasCodes]][source]¶

Group objects with a codes attribute by their codes.

Parameters:: xs (iterable) – Objects to be grouped, each having a codes attribute (e.g. Trace, Channel, Response).
Return type:: dict of CodesNSLCE to list

by_codes_unique(xs: HasCodes) → dict[CodesNSLCE, HasCodes][source]¶

Like by_codes(), but keeping only codes with exactly one matching object, unwrapped from their single-element list.

Parameters:: xs (iterable) – Objects to be grouped, each having a codes attribute.
Return type:: dict of CodesNSLCE to object

class CodesFilterBase(**kwargs)[source]¶

Bases: Object

Base class for codes filters, used to select which of an operator’s input codes it should act on (see BaseOperator.update_mappings()).

filter(it: Sequence[CodesNSLCE]) → List[CodesNSLCE][source]¶

Filter a sequence of codes.

Parameters:: it (iterable of CodesNSLCE) – Codes to be filtered.
Returns:: The base implementation returns all given codes unfiltered; subclasses restrict this.
Return type:: list of CodesNSLCE

class CodesFilter(**kwargs)[source]¶

Bases: CodesFilterBase

Filter by codes patterns.

♦ include¶

list of pyrocko.model.codes.CodesNSLCE objects, optional

If given, only codes matching one of these patterns pass the filter.

♦ exclude¶

list of pyrocko.model.codes.CodesNSLCE objects, optional

If given, codes matching one of these patterns are removed from the filter result, even if they match include.

match(codes)[source]¶

Check if a single codes object passes the filter.

Parameters:: codes (CodesNSLCE) – Codes to be checked.
Return type:: bool

filter(it: Sequence[CodesNSLCE]) → List[CodesNSLCE][source]¶

Filter a sequence of codes by include/ exclude.

Parameters:: it (iterable of CodesNSLCE) – Codes to be filtered.
Return type:: list of CodesNSLCE

class CodesMapping[source]¶

Bases: object

Records which output codes an operator derives from which input codes, for a single output group (internal use, see BaseOperator.iter_mappings()).

Attributes:

in_codes_set¶: Working set of input codes belonging to this mapping, kept in sync incrementally as the input’s available codes change (see Operator._update_mappings_specific()).

in_codes¶: Input codes belonging to this mapping, as a sorted tuple (refreshed from in_codes_set whenever it changes).

out_codes¶: Output codes derived from in_codes, one per Outlet returned by Operator.get_outlets().

group_key¶: Key under which this mapping is grouped (e.g. the input codes’ NSLC-minus-component identifier), as computed by the operator’s grouping logic.

describe()[source]¶

Get one-line summary, as '<n_out> <- <n_in>'.

Return type:: str

new_operator_id()[source]¶

Generate a fresh unique id for an operator instance (see BaseOperator.reset()).

Return type:: uuid.UUID

class Outlet(**kwargs)[source]¶

Bases: Object

Describes one distinct output “channel” of an operator, e.g. one component of a 3-component coordinate transform.

Used by Operator.get_outlets() and consumed by CodesProjection.project() to fill the {o.*} placeholders when deriving output codes.

♦ kinds¶

list of str objects, default: []

Content kinds produced through this outlet, e.g. ['channel', 'waveform'].

♦ attributes¶

dict of str objects, default: {}

Named values substituted for {o.<name>} placeholders in the operator’s codes-projection template, e.g. {'component': 'Z'}.

class InputCombinator(inputs)[source]¶

Bases: object

Transparently fans out queries to several inputs and aggregates the results, giving a combined input the same interface as a single operator/squirrel input (internal use, see BaseOperator.add_input()).

add_input(input)[source]¶

Add an input to the combination.

Parameters:: input (operator or Squirrel) – Input to add.
Raises:: OperatorError – If input is already among the combined inputs.

reset()[source]¶: Reset cached mapping-invalidation state (see update_mappings()).

update_mappings()[source]¶

Propagate a mapping update to all combined inputs and get a counter reflecting the combined update state.

Returns:: A counter, incremented whenever any combined input’s own mapping-update counter has changed since the last call (see BaseOperator.update_mappings()).
Return type:: int

get_time_span(kinds, dummy_limits=True) → Tuple[TimeFloat, TimeFloat][source]¶

Get combined time span across all inputs.

Parameters:

kinds (list of str) – Content kinds to consider.
dummy_limits (bool) – Passed through to each input’s own get_time_span.

Returns:

(tmin, tmax), the earliest start and latest end time across all inputs, or (None, None) if no input reports a defined time span.

Return type:

tuple

iter_in_codes(*args, **kwargs)[source]¶: Iterate over combined, deduplicated, sorted input codes across all inputs. See BaseOperator.iter_in_codes().

iter_codes(*args, **kwargs)[source]¶: Iterate over combined, deduplicated, sorted output codes across all inputs. See BaseOperator.iter_codes().

get_in_codes(*args, **kwargs)[source]¶: Get combined, deduplicated, sorted input codes across all inputs. See BaseOperator.get_in_codes().

get_codes(*args, **kwargs)[source]¶: Get combined, deduplicated, sorted output codes across all inputs. See BaseOperator.get_codes().

get_carpets(*args, **kwargs)[source]¶: Get concatenated carpets across all inputs. See BaseOperator.get_carpets().

get_channels(*args, **kwargs)[source]¶: Get concatenated channels across all inputs. See BaseOperator.get_channels().

get_events(*args, **kwargs)[source]¶: Get concatenated events across all inputs. See BaseOperator.get_events().

get_waveforms(*args, **kwargs)[source]¶: Get concatenated waveforms across all inputs. See BaseOperator.get_waveforms().

get_responses(*args, **kwargs)[source]¶: Get concatenated responses across all inputs. See BaseOperator.get_responses().

get_rich_coverage(*args, **kwargs)[source]¶: Get concatenated rich coverage across all inputs. See get_rich_coverage().

get_sensors(*args, **kwargs)[source]¶: Get concatenated sensors across all inputs. See BaseOperator.get_sensors().

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

Get the common root squirrel of all combined inputs.

Return type:: Squirrel
Raises:: OperatorError – If the combined inputs do not share a single common root squirrel.

advance_accessor(*args, **kwargs)[source]¶: Advance the memory-cache accessor on all combined inputs. See advance_accessor().

class BaseOperator(**kwargs)[source]¶

Bases: Object

Base class for on-demand data-processing operators.

Provides an operator’s generic plumbing (input wiring, codes-mapping bookkeeping, the squirrel-like query methods dispatching through process_*); see the module docstring for the overall concept. Most concrete operators derive from Operator instead, which adds the common filter/group/translate codes_projection machinery; BaseOperator is for operators needing full control over their codes mapping.

♦ name¶

str, default: 'base_op'

Name of this operator, used to refer to it from other operators’ input_names and as a namespacing element in derived data codes.

♦ input_names¶

list of str objects, optional

Names of operators (or 'squirrel') to take as input. If not given, this operator implicitly takes the previous operator (or the squirrel, for the first one) in its Mantra’s operator list; see Mantra._plan_connections().

post_init()[source]¶: Guts post-initialization hook, resetting runtime state (see reset()).

reset()[source]¶: Reset all runtime state (input wiring, codes mapping, mantra association) to a freshly-constructed state.

property kind_provides¶

Content kinds this operator offers to its consumer.

Return type:: tuple of str

property kind_requires¶

Content kinds this operator needs from its input.

Return type:: tuple of str

add_input(input: Operator | Squirrel) → None[source]¶

Add an input to this operator.

Parameters:: input (operator or Squirrel) – Input to add. Multiple inputs are combined transparently (see InputCombinator); normally, inputs are wired up declaratively via a Mantra rather than by calling this directly.
Raises:: Exception – If input does not provide a content kind listed in kind_requires.

get_input() → Operator | Squirrel[source]¶

Get this operator’s input (see add_input()).

Return type:: operator, InputCombinator or Squirrel, or None if no input has been added yet

set_mantra(mantra)[source]¶

Associate this operator with the mantra it belongs to (internal use, called from setup()).

Parameters:: mantra (Mantra) – Owning mantra.

property mantra_name¶: Name of the owning Mantra (see set_mantra()), or '' if not (yet) associated with one.

describe() → str[source]¶

Get textual description of this operator, its outlets and its current codes mapping.

Return type:: str

iter_mappings(codes: List[CodesNSLCE] | None = None) → Generator[CodesMapping, None, None][source]¶

Iterate over this operator’s current codes mappings, refreshing them first (see update_mappings()).

Parameters:: codes (list of CodesNSLCE) – If given, restrict to mappings with at least one matching output code.
Yields:: CodesMapping objects.

get_mappings(codes: List[CodesNSLCE] = None) → List[CodesMapping][source]¶: Get this operator’s current codes mappings, see iter_mappings().

get_mappings_and_matching_codes(codes: tList[CodesNSLCE] | None = None)[source]¶

Get codes mappings together with the subset of their output codes matching a query, refreshing mappings first (see update_mappings()).

Parameters:: codes (list of CodesNSLCE) – If given, restrict to mappings with at least one matching output code, and report only the matching output codes.
Returns:: (mappings, codes_out_match) if codes is given (an empty pair if no mapping matches), else (all mappings, None).
Return type:: tuple of (list of CodesMapping, list of CodesNSLCE or None)

iter_codes() → Generator[CodesNSLCE, None, None][source]¶

Iterate over this operator’s output codes, refreshing mappings first (see update_mappings()).

Yields:: CodesNSLCE objects.

get_codes(kind: str = None) → List[CodesNSLCE][source]¶

Get this operator’s output codes for a given content kind.

Parameters:: kind (str) – Content kind to query. With None, the codes of all provided kinds are returned. A kind not listed in kind_provides yields an empty result rather than an error.
Return type:: list of CodesNSLCE

iter_in_codes(mappings: List[CodesMapping] | None = None) → Generator[CodesNSLCE, None, None][source]¶

Iterate over this operator’s input codes, refreshing mappings first (see update_mappings()).

Parameters:: mappings (list of CodesMapping) – If given, restrict to these mappings’ input codes instead of all current mappings.
Yields:: CodesNSLCE objects.

get_in_codes(mappings: List[CodesMapping] | None = None) → List[CodesNSLCE][source]¶: Get this operator’s input codes, sorted, see iter_in_codes().

update_mappings() → int[source]¶

Refresh this operator’s codes mapping against its input’s currently available codes, if needed.

Cheap to call repeatedly: the input’s own update counter (returned by its update_mappings() method) is checked first, and no work is done unless it has changed since the last call. When it has, the set of available input codes (intersected across all kind_requires kinds, or unfiltered by kind if kind_requires is empty) is diffed against the previous set, and added/removed codes are passed to _update_mappings_specific() (implemented by subclasses, e.g. Operator) to update the mappings.

Returns:: A counter, incremented whenever the mapping actually changed.
Return type:: int

get_in_channels(in_codes: List[CodesNSLCE], tmin: TimeFloat, tmax: TimeFloat) → dict[CodesNSLCE, Channel][source]¶: Get input channels, grouped by codes. See by_codes and process_channels().

get_in_responses(in_codes: List[CodesNSLCE], tmin: TimeFloat, tmax: TimeFloat) → dict[CodesNSLCE, Response][source]¶: Get input responses, grouped by codes. See process_responses().

get_in_waveforms(in_codes: List[CodesNSLCE], tmin: TimeFloat, tmax: TimeFloat, **kwargs) → dict[CodesNSLCE, Trace][source]¶: Get input waveforms, grouped by codes. See process_waveforms().

get_in_carpets(in_codes: List[CodesNSLCE], tmin: TimeFloat, tmax: TimeFloat, **kwargs) → dict[CodesNSLCE, Carpet][source]¶: Get input carpets, grouped by codes. See process_carpets().

get_in_coverages(kind: str, in_codes: List[CodesNSLCE], tmin: TimeFloat, tmax: TimeFloat, **kwargs) → dict[CodesNSLCE, Trace][source]¶: Get input coverage, grouped by codes, keeping at most one coverage entry per codes (see by_codes_unique). See process_coverage().

get_rich_coverage(tmin=None, tmax=None, codes=None, limit=None)[source]¶: Get combined coverage information for channel/response/waveform content kinds, derived through this operator. See get_rich_coverage().

get_channels(obj: HasTimeAndCodes = None, tmin: TimeFloat = None, tmax: TimeFloat = None, time: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None) → List[Channel][source]¶: Get channels derived through this operator. See get_channels().

get_sensors(obj: HasTimeAndCodes = None, tmin: TimeFloat = None, tmax: TimeFloat = None, time: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None) → List[Sensor][source]¶: Get sensors derived through this operator, by grouping get_channels()’ result (see process_sensors()). See also get_sensors()-alike querying.

get_responses(obj: HasTimeAndCodes = None, tmin: TimeFloat = None, tmax: TimeFloat = None, time: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None) → List[Response][source]¶: Get instrument responses derived through this operator. See get_responses().

get_waveforms(obj: HasTimeAndCodes = None, tmin: TimeFloat = None, tmax: TimeFloat = None, time: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None, **kwargs) → List[Trace][source]¶: Get waveforms derived through this operator, padded by get_time_padding() on input before processing (e.g. to give a filter its transient time). See get_waveforms().

get_carpets(obj: HasTimeAndCodes = None, tmin: TimeFloat = None, tmax: TimeFloat = None, time: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None, **kwargs) → List[Carpet][source]¶: Get carpets derived through this operator, padded by get_time_padding() on input before processing. See get_carpets().

chopper_carpets(obj=None, tmin=None, tmax=None, time=None, codes=None, tinc=None, tpad=0.0, want_incomplete=True, snap_window=False)[source]¶

Iterate over carpets derived through this operator, in consecutive time windows. See get_carpets() and pyrocko.util.iter_windows() for windowing parameters.

Yields:: Batch objects, with each window’s carpets in carpets (see get_carpets()).

get_events(obj: HasTimeAndCodes = None, tmin: TimeFloat = None, tmax: TimeFloat = None, time: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None, **kwargs) → List[Event][source]¶: Get events. Not currently implemented by any operator; always returns an empty list, regardless of input.

get_squirrel()[source]¶

Get the root Squirrel this operator ultimately derives its content from, following the input chain.

Return type:: Squirrel

advance_accessor(accessor_id='default', cache_id=None)[source]¶: Advance the memory-cache accessor on the input. See advance_accessor().

chopper_waveforms(obj=None, tmin=None, tmax=None, time=None, codes=None, codes_exclude=None, sample_rate_min=None, sample_rate_max=None, tinc=None, tpad=0.0, want_incomplete=True, snap_window=False, degap=True, maxgap=5, maxlap=None, snap=None, include_last=False, load_data=True, accessor_id=None, clear_accessor=True, group_by=None, channel_priorities=None)[source]¶

Iterate over waveforms derived through this operator, in consecutive time windows.

Parameters:

tinc (float) – Time window length [s]. If not given, a single window covering the whole queried time span is used.
tpad (float) – Padding time [s] added symmetrically to each window before processing (see get_waveforms()) and reported back via tpad.
snap_window (bool) – If True, snap window start/end to multiples of tinc.
group_by (str) – If given, a codes-projection group-by template (see CodesProjection.group_by) to additionally split each time window into separate batches per matching group of output codes (e.g. to chop each sensor separately). By default, all matching codes are chopped together into a single group per window.
accessor_id (str) – Name of consumer on whose behalf data is accessed (see get_waveforms()). By default, a name unique to this operator instance and chopper invocation is generated.
clear_accessor (bool) – If True (the default), release cached waveform data held for accessor_id once the chopper is exhausted or aborted.
channel_priorities – See get_waveforms()’s parameter of the same name.

See get_waveforms() for the remaining parameters (obj, tmin, tmax, time, codes, codes_exclude, sample_rate_min, sample_rate_max, want_incomplete, degap, maxgap, maxlap, snap, include_last, load_data), applied per window.

Yields:: Batch objects, one per time window (times ngroups, if group_by is given).

get_coverage(kind, tmin: TimeFloat = None, tmax: TimeFloat = None, codes: CodesNSLCE | List[CodesNSLCE] | str | List[str] | Tuple[str] | List[Tuple[str]] = None, limit=None) → List[Coverage][source]¶: Get coverage information derived through this operator. See get_coverage().

process_channels(mappings: List[CodesMapping], in_codes: List[CodesNSLCE], codes_to_channels: dict[CodesNSLCE, List[Channel]], tmin: TimeFloat = None, tmax: TimeFloat = None) → List[Channel][source]¶

Derive output channels from input channels, cloning and reprojecting codes according to mappings (default implementation, suitable for operators which do not need to modify channel objects themselves).

Parameters:

mappings (list of CodesMapping) – Codes mappings to derive output channels for (see get_mappings()/get_mappings_and_matching_codes()).
in_codes (list of CodesNSLCE) – Unused in the default implementation (present for API consistency and for use by overriding implementations).
codes_to_channels (dict) – Input channels, keyed by input codes (see get_in_channels()).
tmin – Unused in the default implementation.
tmax – Unused in the default implementation.

Return type:

list of Channel

process_sensors(channels: List[Channel], tmin: TimeFloat = None, tmax: TimeFloat = None) → List[Sensor][source]¶

Group channels into sensors (default implementation, see from_channels()).

Parameters:: channels (list of Channel) – Output channels to be grouped, as returned by process_channels().
Return type:: list of Sensor

process_responses(mappings: List[CodesMapping], in_codes: List[CodesNSLCE], codes_to_responses: dict[CodesNSLCE, List[Response]], tmin: TimeFloat = None, tmax: TimeFloat = None) → List[Response][source]¶

Derive output responses from input responses, cloning and reprojecting codes according to mappings. Parameters as for process_channels().

Return type:: list of Response

process_waveforms(mappings: List[CodesMapping], in_codes: List[CodesNSLCE], codes_to_traces: dict[CodesNSLCE, List[Trace]], tmin: TimeFloat = None, tmax: TimeFloat = None) → List[Trace][source]¶

Derive output waveforms from input waveforms, copying and reprojecting codes according to mappings (default implementation, suitable for operators which do not transform the samples; see Restitution.process_waveforms() for an example which does). The copies share the sample data with the input traces.

Parameters as for process_channels(), with codes_to_traces in place of codes_to_channels.

Return type:: list of Trace

process_carpets(mappings: List[CodesMapping], in_codes: List[CodesNSLCE], codes_to_carpets: dict[CodesNSLCE, List[Carpet]], tmin: TimeFloat = None, tmax: TimeFloat = None) → List[Carpet][source]¶

Derive output carpets from input carpets, copying and reprojecting codes according to mappings (default implementation, suitable for operators which do not transform the data; subclasses producing new carpets override this, e.g. CarpetSum.process_carpets()). The copies share the data with the input carpets.

Parameters as for process_channels(), with codes_to_carpets in place of codes_to_channels.

Return type:: list of Carpet

process_coverage(mappings: List[CodesMapping], in_codes: List[CodesNSLCE], codes_to_coverage: dict[CodesNSLCE, Coverage], tmin: TimeFloat = None, tmax: TimeFloat = None) → List[Trace][source]¶

Derive output coverage from input coverage, by joining (join_coverages()) each mapping’s input coverages, padded by get_time_padding(), and re-tagging the result with each of the mapping’s out_codes.

Parameters as for process_channels(), with codes_to_coverage in place of codes_to_channels.

Return type:: list of Coverage

get_time_padding() → float[source]¶: Get extra time span [s] this operator needs from its input on each side of a query’s time span (e.g. filter transient time), used by get_waveforms()/get_carpets()/ get_coverage()/get_time_span() to pad input queries and shrink the reported available time span accordingly. Default: 0.0; overridden e.g. by Restitution.get_time_padding().

get_time_span(kinds, dummy_limits=True) → Tuple[TimeFloat, TimeFloat][source]¶

Get time span available through this operator, shrunk on both ends by get_time_padding() relative to the input’s own time span.

Parameters:

kinds (list of str) – Content kinds to consider.
dummy_limits (bool) – Passed through to the input’s own get_time_span.

Returns:

(tmin, tmax), or (None, None) if the input reports an undefined time span.

Return type:

tuple

class CodesProjectionBase(**kwargs)[source]¶

Bases: CodesFilter

Base class for codes projections: combined filter, grouping and codes-derivation strategies used by Operator (see Operator.codes_projection).

group_key(codes)[source]¶

Get the key under which a given input codes should be grouped with others sharing the same key (e.g. to combine a sensor’s component channels into one mapping).

Parameters:: codes (CodesNSLCE) – Input codes to compute the group key for.

project(operator, codes, outlets)[source]¶

Derive output codes for a group of input codes.

Parameters:

operator (Operator or None) – Operator this projection belongs to (used e.g. to fill {o.name}/{o.mantra} template placeholders), or None.
codes (iterable of CodesNSLCE) – Input codes sharing a common group_key().
outlets (list of Outlet) – The operator’s outlets (see Operator.get_outlets()), one output code is derived per outlet.

class CodesProjection(template=None, group_by=None, **kwargs)[source]¶

Bases: CodesProjectionBase

Template-string-based codes projection.

Groups and derives codes using Python str.format-style templates with {i.<attr>}/{o.<attr>} placeholders, referring to the input codes’ attributes (network, station, location, channel, extra, and the extra attributes defined on CodesNSLCE, e.g. channel_no_component) and to the producing Outlet’s attributes plus the operator’s name/mantra (unset {o.*} placeholders resolve to the empty string when no outlet/operator context is given, e.g. when used standalone for group_by).

♦ template¶

str, default: '{i.network}.{i.station}.{i.location}.{i.channel}.{i.extra}'

Template used to derive output codes from a group of input codes and an outlet, e.g. '{i.network}.{i.station}.{i.location}.{i.channel}'.

♦ group_by¶

str, optional

Template used to compute the grouping key for input codes (see group_key()). Defaults to template itself, appropriate when the projection does not aggregate multiple input codes (e.g. no {o.*} placeholders).

group_key(codes)[source]¶

Get grouping key for input codes, from group_by (or template, if unset).

Parameters:: codes (CodesNSLCE) – Input codes to compute the group key for.
Return type:: str

project(operator, codes_group, outlets)[source]¶

Derive output codes for a group of input codes, from template, for every input-codes/outlet combination.

Parameters:

operator (Operator or None) – Operator this projection belongs to, or None.
codes_group (iterable of CodesNSLCE) – Input codes sharing a common group_key().
outlets (list of Outlet) – The operator’s outlets.

Returns:

Deduplicated, sorted output codes.

Return type:

tuple of CodesNSLCE

basic_codes_projection_t(template)[source]¶

Get a Guts field definition for a Operator.codes_projection attribute, defaulting to a CodesProjection with a given template.

Parameters:: template (str) – Default CodesProjection.template string.
Return type:: Guts field definition (see CodesProjectionBase.T)

class Operator(**kwargs)[source]¶

Bases: BaseOperator

Base class for operators with typical filter-group-translate behaviour.

Adds the generic codes_projection-driven codes-mapping machinery on top of BaseOperator: input codes are filtered, grouped and projected to output codes automatically (see CodesProjection), so concrete subclasses (e.g. Restitution, Transform) typically only need to declare a codes_projection, override get_outlets() and implement the relevant process_* method(s).

♦ name¶

str, default: 'op'

Name of this operator, see name.

♦ codes_projection¶

CodesProjectionBase, default: CodesProjection(template='{i.network}.{i.station}.{i.location}.{i.channel}.{i.extra}')

get_outlets()[source]¶: Get this operator’s outlets (default: a single, generic Outlet with no declared kinds/attributes; concrete subclasses normally override this).

class Restitution(**kwargs)[source]¶

Bases: Operator

Removes the instrument response, restituting to a chosen physical quantity.

Requires 'waveform' and 'response' from its input and provides 'channel'/'waveform'. Output codes get an R<quantity-letter> suffix appended to the channel’s extra code (e.g. RV for velocity).

♦ name¶

str, default: 'rest'

♦ codes_projection¶

CodesProjectionBase, default: CodesProjection(template='{i.network}.{i.station}.{i.location}.{i.channel}.{i.extra}R{o.quantity}')

♦ quantity¶

str (pyrocko.squirrel.model.QuantityType), default: 'velocity'

Physical quantity to restitute to.

♦ frequency_min¶

float

Lower corner frequency of the deconvolution passband [Hz].

♦ frequency_max¶

float

Upper corner frequency of the deconvolution passband [Hz].

♦ frequency_taper_factor¶

float, default: 1.5

Factor by which frequency_min/frequency_max are divided/multiplied to get the default taper corner frequencies, if not given explicitly.

♦ frequency_taper_min¶

float, optional

Lower taper corner frequency [Hz], overriding the default derived from frequency_min/frequency_taper_factor.

♦ frequency_taper_max¶

float, optional

Upper taper corner frequency [Hz], overriding the default derived from frequency_max/frequency_taper_factor.

♦ time_taper_factor¶

float, default: 2.0

Factor controlling the time-domain taper length and, via time_padding_extra_factor, the input time padding requested from upstream (see get_time_padding()).

♦ time_padding_extra_factor¶

float, default: 2.0

Extra safety factor applied on top of time_taper_factor when computing the input time padding requested from upstream (see get_time_padding()).

get_outlets() → List[Outlet][source]¶: Get outlets: a single one, tagged with the restituted quantity’s first letter (used as {o.quantity} in codes_projection).

get_time_padding() → float[source]¶: Get input time padding needed for the deconvolution’s time-domain taper, derived from frequency_min, time_taper_factor and time_padding_extra_factor.

get_taper_frequencies()[source]¶

Get the four corner frequencies of the deconvolution’s frequency taper, as (f1, f2, f3, f4) (see pyrocko.trace.Trace.transfer()’s freqlimits).

Return type:: tuple of 4 float

Deconvolve the instrument response from each input trace and restitute to quantity, skipping (with a logged warning) traces with missing, ambiguous, or too-low-sample-rate responses, or which raise TraceTooShort, NoData or InvalidResponseError during deconvolution.

Parameters as for process_channels(), with codes_to_traces in place of codes_to_channels.

class Transform(**kwargs)[source]¶

Bases: Operator

Base class for coordinate-system transforms (see ToENZ, ToTRZ, ToLQT), rotating each group of matching channels (via project_to_enz()-alike sensor projections) into a new component system.

Requires and provides 'channel'/'waveform'. Output codes get the component character replaced by the target system’s component (e.g. E/N/Z) and a T<system> suffix appended to the extra code (e.g. TENZ).

♦ name¶

str, default: 'trans'

♦ codes_projection¶

CodesProjectionBase, default: CodesProjection(template='{i.network}.{i.station}.{i.location}.{i.channel_no_component}{o.component}.{i.extra}T{o.system}')

get_outlets()[source]¶: Get outlets: one per target components character, tagged with the target system (lower-cased components, used as {o.system}) and that component (used as {o.component}) in codes_projection.

get_component_codes(mapping)[source]¶

Get output codes of a mapping by target component character.

Parameters:: mapping (CodesMapping) – Codes mapping of this operator.
Returns:: Output codes, keyed by component character.
Return type:: dict

Derive rotated output channels, one triplet per input sensor (group of matching input channels), with azimuth/dip set from get_orientation() (implemented by subclasses).

Parameters as for process_channels().

Rotate each mapping’s input traces (which must form exactly one sensor’s worth of channels) into the target component system via project() (implemented by subclasses), skipping (with a logged warning) mappings whose input codes don’t group into exactly one sensor.

Parameters as for process_channels(), with codes_to_traces in place of codes_to_channels.

class ToENZ(**kwargs)[source]¶

Bases: Transform

Rotate sensors to East-North-Up components.

See Transform for what’s required/provided and how output codes are derived.

♦ name¶

str, default: 'enz'

project(sensor, trs_sensor)[source]¶: Rotate a sensor’s traces to ENZ, see project_to_enz().

get_orientation(sensor, component)[source]¶: Get (azimuth, dip) for a given ENZ component character.

class ToTRZ(**kwargs)[source]¶

Bases: Transform

Rotate sensors to Transverse-Radial-Up components, relative to a source or a fixed backazimuth.

The backazimuth is computed for each sensor from origin, unless given explicitly with backazimuth, in which case it applies to all sensors.

See Transform for what’s required/provided and how output codes are derived.

♦ name¶

str, default: 'trz'

♦ origin¶

pyrocko.model.location.Location, optional

Source location to compute the backazimuth from. Required unless backazimuth is given.

♦ backazimuth¶

float, optional

Backazimuth [deg], i.e. direction from the sensors towards the source, measured clockwise from north, overriding the value computed from origin.

get_backazimuth(sensor)[source]¶: Get backazimuth [deg] at a sensor, see backazimuth.

project(sensor, trs_sensor)[source]¶: Rotate a sensor’s traces to TRZ, see project_to_trz().

get_orientation(sensor, component)[source]¶: Get (azimuth, dip) for a given TRZ component character.

class ToLQT(**kwargs)[source]¶

Bases: Transform

Rotate sensors to Longitudinal-Transverse-SH (ray-based) components, relative to a source and earth model.

Backazimuth and incidence angle are computed for each sensor from origin, unless given explicitly with backazimuth and incidence. Explicit values apply to all sensors, i.e. they describe a plane wave, e.g. for the sensors of an array. They are used consistently for the rotation of the waveforms and for the orientations of the output channels.

See Transform for what’s required/provided and how output codes are derived.

♦ name¶

str, default: 'lqt'

♦ origin¶

pyrocko.model.location.Location, optional

Source location to compute backazimuth and incidence angle from. Required unless backazimuth and incidence are given, or backazimuth, distance and source_depth.

♦ earthmodel¶

pyrocko.cake.LayeredModel (pyrocko.gf.meta.Earthmodel1D), optional

Earth model used for automatic incidence angle computation. Defaults to a built-in global model, see get_default_earthmodel().

♦ phases¶

list of str objects, default: []

Candidate seismic phases to use for automatic incidence angle computation, in Cake phase syntax. Default: p, P.

♦ distance¶

float, optional

Source-sensor distance [deg] for automatic incidence angle computation, overriding the distance computed from origin.

♦ source_depth¶

float, optional

Source depth [m] for automatic incidence angle computation, overriding the depth of origin.

♦ backazimuth¶

float, optional

Backazimuth [deg], i.e. direction from the sensors towards the source, measured clockwise from north, overriding the value computed from origin.

♦ incidence¶

float, optional

Incidence angle [deg], measured from vertical, overriding the automatic computation.

get_backazimuth(sensor)[source]¶: Get backazimuth [deg] at a sensor, see backazimuth.

get_incidence(sensor)[source]¶: Get incidence angle [deg] at a sensor, see incidence.

project(sensor, trs_sensor)[source]¶: Rotate a sensor’s traces to LQT, see project_to_lqt().

get_orientation(sensor, component)[source]¶: Get (azimuth, dip) for a given LQT component character.

class CarpetSum(**kwargs)[source]¶

Bases: Operator

Sum (or average) all input carpets into a single combined carpet.

Requires and provides 'carpet'. Its codes_projection has no {i.*}/{o.*} placeholders, so all input carpets are grouped into one and summed together, regardless of station/network — e.g. to stack a whole array’s carpets into one. Output codes are fixed to '.SUM...' (empty network/location/channel/extra, station 'SUM').

♦ name¶

str, default: 'csum'

♦ codes_projection¶

CodesProjectionBase, default: CodesProjection(template='.SUM...')

♦ nan_aware¶

bool, default: False

Treat NaNs as zero.

♦ normalize¶

bool, default: False

Calculate average.

get_outlets()[source]¶: Get outlets: a single one, tagged 'carpet'.

Sum each mapping’s input carpets (see pyrocko.carpet.sum()), controlled by nan_aware /normalize, skipping (with a logged warning) mappings where summation fails (e.g. incompatible carpet geometries).

Parameters as for process_channels(), with codes_to_carpets in place of codes_to_channels.

class CarpetHOverV(**kwargs)[source]¶

Bases: Operator

Combine horizontal (N/E) and vertical (Z) component carpets into a single horizontal-to-vertical ratio carpet, per sensor.

Requires and provides 'carpet'. The input carpets must contain logarithmic values, as produced by the spectrogram operators (see pyrocko.squirrel.operators.spectrogram), whose carpets hold the natural logarithm of the power spectrum. The horizontal components are averaged, as are the vertical ones, and the vertical average is subtracted from the horizontal one. In the logarithmic domain, the average corresponds to a geometric mean and the subtraction to a ratio, so for spectrogram input, the result is

$\ln \frac{\sqrt{P_N P_E}}{P_Z},$

the natural logarithm of the H/V power ratio, or twice the natural logarithm of the H/V amplitude ratio. Output codes get an HV suffix appended to the channel’s extra code, with the component character dropped.

♦ name¶

str, default: 'chv'

♦ codes_projection¶

CodesProjectionBase, default: CodesProjection(template='{i.network}.{i.station}.{i.location}.{i.channel_no_component}.{i.extra}HV')

get_outlets()[source]¶: Get outlets: a single one, tagged 'carpet'.

Compute the H/V combination for each mapping’s input carpets, splitting them by component character ('N'/'E' vs. 'Z'), averaging each group (see pyrocko.carpet.sum()) and subtracting the vertical average from the horizontal one. The input values must be logarithmic, see CarpetHOverV. Mappings where this fails (e.g. incompatible carpet geometries, or a missing component) are skipped with a logged warning.

Parameters as for process_channels(), with codes_to_carpets in place of codes_to_channels.

Navigation

pyrocko.squirrel.operators.base¶

Navigation