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 (Union[WaveformClient, str, Path, Trace, Stream, WaveBank]) – Any argument from which a waveform client can be extracted. This includes an obspy waveforms, directory of waveform files, or an object with a get_waveforms method.

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

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

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

  • stream_processor (Optional[Callable[[Stream], Stream]]) – A callable that takes an obspy waveforms as input and returns an obspy waveforms.

  • time_before (Optional[float]) – The default time before an given time to fetch.

  • time_after (Optional[float]) – The default time after a supplied time to fetch.

  • event_query (Optional[dict]) – 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 (Optional[float]) – The time before (in seconds) the reference that will be included in the waveforms if possible.

  • time_after (Optional[float]) – The Time after (in seconds) the reference that will be included in the waveforms if possible.

  • reference (Union[str, Callable]) –

    A str that indicates how the starttime of the trace should be determined. The following are supported:

    origin - use the origin time of the event for each channel p - use the first p times as the start of the station traces s - use the first s times as the start of the station traces

    If a station doesn’t have p or s picks and “p” or “s” is used, it’s streams will not be returned.

  • raise_on_fail (bool) – If True, re raise and 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.

{get_waveform_parameters}

Return type:

Stream

property picks_df

return a dataframe from the picks (if possible)

reference_funcs = {'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 (Union[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 (Union[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 (Union[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 (Optional[float]) – The time before (in seconds) the reference that will be included in the waveforms if possible.

  • time_after (Optional[float]) – The Time after (in seconds) the reference that will be included in the waveforms if possible.

  • reference (Union[str, Callable]) –

    A str that indicates how the starttime of the trace should be determined. The following are supported:

    origin - use the origin time of the event p - use the first p time as the start for each station s - use the first s times as the start for each 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.