obsplus.structures.fetcher module

Data fetcher class stuff

class obsplus.structures.fetcher.EventStream(event_id, stream)

Bases: tuple

event_id

Alias for field number 0

stream

Alias for field number 1

class obsplus.structures.fetcher.Fetcher(waveforms, stations=None, events=None, picks=None, stream_processor=None, time_before=None, time_after=None, event_query=None)[source]

Bases: object

A class for serving up data from various sources.

Integrates station, event, and waveform clients to enable dataset-aware querying.

Parameters:

  • waveforms (WaveformClient | str | Path | Trace | Stream | WaveBank) – Any argument from which a waveform client can be extracted. This includes an ObsPy Stream, a directory of waveform files, or an object with a get_waveforms method.

  • stations (Path | str | Catalog | Event | EventClient | DataFrame | EventBank | None) – Any argument from which a station client can be extracted. This includes an ObsPy Inventory, a directory of station files, or an object with a get_stations method.

  • events (Path | str | Catalog | Event | EventClient | DataFrame | EventBank | None) – Any argument from which an event client can be extracted. This includes an ObsPy Catalog, a directory of event files, or an object with a get_events method.

  • picks (DataFrame | None) – Data from which picks can be extracted. A dataframe, events, or event_client are all acceptable.

  • stream_processor (Callable[[Stream], Stream] | None) – A callable that takes an ObsPy Stream as input and returns an ObsPy Stream.

  • time_before (float | None) – The default time before an given time to fetch.

  • time_after (float | None) – The default time after a supplied time to fetch.

  • event_query (dict | None) – A dict of arguments used to filter events.

Examples

>>> import obsplus
>>> import obspy

>>> #--- Init a Fetcher
>>> # from a dataset
>>> ds = obsplus.load_dataset('bingham_test')
>>> ds_fetcher = ds.get_fetcher()
>>> assert isinstance(ds_fetcher, obsplus.Fetcher)
>>> # from separate clients (includes Stream, Inventory, Catalog)
>>> waveforms = ds.waveform_client
>>> events = ds.event_client
>>> stations = ds.station_client
>>> kwargs = dict(events=events, waveforms=waveforms, stations=stations)
>>> fetcher = obsplus.Fetcher(**kwargs)
>>> assert isinstance(fetcher, obsplus.Fetcher)

>>> # --- get contiguous (not event) waveform data
>>> # simple get_waveform calls are passed to the waveforms client
>>> fetcher = obsplus.load_dataset('ta_test').get_fetcher()
>>> t1 = obspy.UTCDateTime('2007-02-15')
>>> t2 = t1 + 60
>>> station = 'M14A'
>>> st = fetcher.get_waveforms(starttime=t1, endtime=t2, station=station)
>>> print(st)
3 Trace(s) ...
>>> # iterate over a range of times
>>> t1 = obspy.UTCDateTime('2007-02-16')
>>> t2 = t1 + (3600 * 24)
>>> for st in fetcher.yield_waveforms(starttime=t1, endtime=t2):
...     assert len(st)

>>> # --- get event waveforms
>>> fetcher = obsplus.load_dataset('bingham_test').get_fetcher()
>>> # iterate each event yielding streams 30 seconds after origin
>>> kwargs = dict(time_before=0, time_after=30, reference='origin')
>>> for event_id, st in fetcher.yield_event_waveforms(**kwargs):
...     assert isinstance(event_id, str)
...     assert isinstance(st, obspy.Stream)
copy()[source]

Return a deep copy of the fetcher.

Return type:

Fetcher

get_event_waveforms(time_before=None, time_after=None, reference='origin', raise_on_fail=True)[source]

Return a dict of event_ids and waveforms for each event in events.

Parameters:

  • time_before (float | None) – The time before (in seconds) the reference that will be included in the waveforms if possible.

  • time_after (float | None) – The time after (in seconds) the reference that will be included in the waveforms if possible.

  • reference (str | Callable) – A str that indicates how the starttime of the trace should be determined. The following are supported: origin (use the event origin time for each channel), p (use the first P-pick for station traces), and s (use the first S-pick for station traces). If a station doesn’t have p or s picks and “p” or “s” is used, its streams will not be returned.

  • raise_on_fail (bool) – If True, re-raise an exception if one is caught during waveform fetching, else continue to next event.

Yields:

obspy.Stream

Return type:

dict[str, Stream]

get_waveforms(*args, **kwargs)[source]

Get waveforms for all channels in stations.

Return type:

Stream

networkstr

The network code

stationstr

The station code

locationstr

The location code

channelstr

The channel code

starttimefloat or obspy.UTCDateTime

The desired starttime of the waveforms

endtimefloat or obspy.UTCDateTime

The desired endtime of the waveforms

property picks_df

Return a dataframe from the picks (if possible)

reference_funcs: ClassVar = {'origin': <function _get_origin_reference_times>, 'p': <function _get_p_reference_times>, 's': <function _get_s_reference_times>}
set_events(events)[source]

Set event state in fetcher.

Parameters:

events (Path | str | Catalog | Event | EventClient | DataFrame | EventBank) – Data representing events, from which a client or dataframe can be obtained.

set_stations(stations)[source]

Set the station state in fetcher.

Parameters:

stations (str | Path | Inventory | DataFrame) – Data representing stations, from which a client or dataframe can be inferred.

set_waveforms(waveforms)[source]

Set waveform state in Fetcher.

Parameters:

waveforms (WaveformClient | str | Path | Trace | Stream | WaveBank) – Data representing waveforms, from which a wave client can be inferred.

yield_event_waveforms(time_before=None, time_after=None, reference='origin', raise_on_fail=True)[source]

Yield event_id and streams for each event.

Parameters:

  • time_before (float | None) – The time before (in seconds) the reference that will be included in the waveforms if possible.

  • time_after (float | None) – The time after (in seconds) the reference that will be included in the waveforms if possible.

  • reference (str | Callable) – A str that indicates how the starttime of the trace should be determined. The following are supported: origin (use the event origin time), p (use the first P-pick per station), and s (use the first S-pick per station). If “p” or “s” is used only streams corresponding to stations with the appropriate phase pick will be returned.

  • raise_on_fail (bool) – If True, re-raise an exception if one is caught during waveform fetching, else continue to next event.

Return type:

tuple[str, Stream]

Notes

Streams will not be yielded for any event for which a reference time cannot be obtained. For example, if reference=’S’ only events with some S picks will be yielded.

yield_waveforms(network=None, station=None, location=None, channel=None, starttime=None, endtime=None, duration=3600.0, overlap=None)[source]

Yield time-series segments from the waveform client.

Parameters:

  • network (str) – The network code

  • station (str) – The station code

  • location (str) – The location code

  • channel (str) – The channel code

  • starttime (float or obspy.UTCDateTime) – The desired starttime of the waveforms

  • endtime (float or obspy.UTCDateTime) – The desired endtime of the waveforms

  • duration (float) – The duration of the streams to yield. All channels selected channels will be included in the waveforms.

  • overlap (float) – If duration is used, the amount of overlap in yielded streams, added to the end of the waveforms.

Return type:

Stream

Notes

All string parameters can use posix style matching with * and ? chars.

Total duration of yielded streams = duration + overlap.

If no starttime or endtime is provided the min/max indicated by the stations will be used.