obsplus.bank.eventbank module

Class for interacting with events on a filesystem.

class obsplus.bank.eventbank.EventBank(base_path='.', path_structure=None, name_structure=None, format='quakeml', ext='.xml', executor=None)[source]

Bases: _Bank

A class to interact with a directory of event files.

EventBank recursively reads each event file in a directory and creates an index to allow the files to be efficiently queried.

Implements a superset of the EventClient interface.

Parameters:

  • base_path (Union[str, Path, EventBank]) – The path to the directory containing event files. If it does not exist an empty directory will be created.

  • path_structure (Optional[str]) –

    Defines the directory structure used by the event bank. Characters are separated by /, regardless of operating system. The following words can be used in curly braces as data specific variables:

    year, month, day, julday, hour, minute, second, event_id, event_id_short

    If no structure is provided it will be read from the index, if no index exists the default is {year}/{month}/{day}.

  • name_structure (Optional[str]) – The same as path structure but for the file name. Supports the same variables and a slash cannot be used in a file name on most operating systems. The default extension (.xml) will be added. The default is {time}_{event_id_short}.

  • format – The anticipated format of the event files. Any format supported by the obspy.read_events function is permitted.

  • ext – The extension on the files. Can be used to avoid parsing non-event files.

  • executor (Optional[Executor]) – An executor with the same interface as :py:class:`concurrent.futures.Executor, the map method of the executor will be used for reading files and updating indices.

allow_update_timestamp

If True, allow the bank to update its index timestamp. The default value of True is appropriate for all but some very complicated setups.

Examples

>>> # --- Create an `EventBank` from a path to a directory with quakeml files.
>>> import obsplus
>>> event_path = obsplus.copy_dataset('default_test').event_path
>>> # init an EventBank and index the event files.
>>> ebank = obsplus.EventBank(event_path).update_index()

>>> # --- Retrieve catalog objects from the bank.
>>> cat = ebank.get_events(minmagnitude=4.3, minlatitude=40.12)
>>> print(cat)
1 Event(s) in Catalog:...

>>> # --- Put event files bank into the bank.
>>> # get an event from another dataset, keep track of its id
>>> ds = obsplus.load_dataset('bingham_test')
>>> new_events = ds.event_client.get_events(limit=1)
>>> new_event_id = str(new_events[0].resource_id)
>>> # put the event into the EventBank
>>> _ = ebank.put_events(new_events)
>>> print(ebank.get_events(eventid=new_event_id))
1 Event(s) in Catalog:...

>>> # --- Read the index used by EventBank as a DataFrame.
>>> df = ebank.read_index()
>>> assert len(df) == 4, 'there should now be 4 events in the bank.'
allow_update_timestamp = True
get_event_summary(**kwargs)

Read the index and return a dataframe containing the event info.

Parameters:

  • starttime (obspy.UTCDateTime or valid input to such, optional) – Limit to events on or after the specified start time.

  • endtime (obspy.UTCDateTime or valid input to such, optional) – Limit to events on or before the specified end time.

  • minlatitude (float, optional) – Limit to events with a latitude larger than the specified minimum.

  • maxlatitude (float, optional) – Limit to events with a latitude smaller than the specified maximum.

  • minlongitude (float, optional) – Limit to events with a longitude larger than the specified minimum.

  • maxlongitude (float, optional) – Limit to events with a longitude smaller than the specified maximum.

  • latitude (float, optional) – Specify the latitude to be used for a radius search.

  • longitude (float, optional) – Specify the longitude to the used for a radius search.

  • minradius (float, optional) – Limit to events within the specified minimum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • maxradius (float, optional) – Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • mindepth (float, optional) – Limit to events with depth, in kilometers, larger than the specified minimum.

  • maxdepth (float, optional) – Limit to events with depth, in kilometers, smaller than the specified maximum.

  • minmagnitude (float, optional) – Limit to events with a magnitude larger than the specified minimum.

  • maxmagnitude (float, optional) – Limit to events with a magnitude smaller than the specified maximum.

  • magnitudetype (str, optional) – Specify a magnitude type to use for testing the minimum and maximum limits.

  • eventid (str (or sequence of such), optional) – Select specific event(s) by ID.

  • limit (int, optional) – Limit the results to the specified number of events.

  • offset (int, optional) – Return results starting at the event count specified, starting at 1.

  • contributor (str, optional) – Limit to events contributed by a specified contributor.

  • updatedafter (obspy.UTCDateTime or valid input to such, optional) – Limit to events updated after the specified time.

  • degrees (int, default True) – If False, the parameters maxradius and minradius are specified in m rather than degrees. Note: this parameter may not be supported by non-obsplus event clients.

Return type:

DataFrame

get_events(**kwargs)[source]

Read events from bank.

Parameters:

  • starttime (obspy.UTCDateTime or valid input to such, optional) – Limit to events on or after the specified start time.

  • endtime (obspy.UTCDateTime or valid input to such, optional) – Limit to events on or before the specified end time.

  • minlatitude (float, optional) – Limit to events with a latitude larger than the specified minimum.

  • maxlatitude (float, optional) – Limit to events with a latitude smaller than the specified maximum.

  • minlongitude (float, optional) – Limit to events with a longitude larger than the specified minimum.

  • maxlongitude (float, optional) – Limit to events with a longitude smaller than the specified maximum.

  • latitude (float, optional) – Specify the latitude to be used for a radius search.

  • longitude (float, optional) – Specify the longitude to the used for a radius search.

  • minradius (float, optional) – Limit to events within the specified minimum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • maxradius (float, optional) – Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • mindepth (float, optional) – Limit to events with depth, in kilometers, larger than the specified minimum.

  • maxdepth (float, optional) – Limit to events with depth, in kilometers, smaller than the specified maximum.

  • minmagnitude (float, optional) – Limit to events with a magnitude larger than the specified minimum.

  • maxmagnitude (float, optional) – Limit to events with a magnitude smaller than the specified maximum.

  • magnitudetype (str, optional) – Specify a magnitude type to use for testing the minimum and maximum limits.

  • eventid (str (or sequence of such), optional) – Select specific event(s) by ID.

  • limit (int, optional) – Limit the results to the specified number of events.

  • offset (int, optional) – Return results starting at the event count specified, starting at 1.

  • contributor (str, optional) – Limit to events contributed by a specified contributor.

  • updatedafter (obspy.UTCDateTime or valid input to such, optional) – Limit to events updated after the specified time.

  • degrees (int, default True) – If False, the parameters maxradius and minradius are specified in m rather than degrees. Note: this parameter may not be supported by non-obsplus event clients.

Return type:

Catalog

ids_in_bank(event_id)[source]

Determine if one or more event_ids are used by the bank.

This function is faster than reading the entire index into memory to perform a similar check.

Parameters:

event_id (Union[str, Sequence[str]]) – A single event id or sequence of event ids.

Return type:

Set[str]

Returns:

A set of event_ids which are also found in the bank.

index_name = '.index.db'
property last_updated_timestamp

Return the last modified time stored in the index, else 0.0

namespace = '/events'
put_events(events, update_index=True, bar=None, overwrite_existing=True)[source]

Put events into the EventBank.

If the event_id already exists the old event will be overwritten on disk.

Parameters:

  • events (Union[Event, Catalog, EventClient]) – An objects which contains event data (e.g. Catalog, Event, EventBank, etc.)

  • update_index (bool) – Flag to indicate whether or not to update the event index after writing the new events. Note: Only events added through this method call will get indexed. Default is True.

  • bar (Optional[ProgressBar]) –

    This parameter controls if a progress bar will be used for this function call. Its behavior is dependent on the bar parameter:

    False - Don’t use a progress bar None - Use the default progress bar ProgressBar - a custom implementation of progress bar is used.

    If a custom progress bar is to be used, it must have an update and finish method.

  • overwrite_existing – If True, overwrite any existing events in the EventBank which share an event id with the new events.

Return type:

EventBank

Notes

If any of the events do not have an extractable reference time a ValueError will be raised.

read_index(**kwargs)[source]

Read the index and return a dataframe containing the event info.

Parameters:

  • starttime (obspy.UTCDateTime or valid input to such, optional) – Limit to events on or after the specified start time.

  • endtime (obspy.UTCDateTime or valid input to such, optional) – Limit to events on or before the specified end time.

  • minlatitude (float, optional) – Limit to events with a latitude larger than the specified minimum.

  • maxlatitude (float, optional) – Limit to events with a latitude smaller than the specified maximum.

  • minlongitude (float, optional) – Limit to events with a longitude larger than the specified minimum.

  • maxlongitude (float, optional) – Limit to events with a longitude smaller than the specified maximum.

  • latitude (float, optional) – Specify the latitude to be used for a radius search.

  • longitude (float, optional) – Specify the longitude to the used for a radius search.

  • minradius (float, optional) – Limit to events within the specified minimum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • maxradius (float, optional) – Limit to events within the specified maximum number of degrees from the geographic point defined by the latitude and longitude parameters.

  • mindepth (float, optional) – Limit to events with depth, in kilometers, larger than the specified minimum.

  • maxdepth (float, optional) – Limit to events with depth, in kilometers, smaller than the specified maximum.

  • minmagnitude (float, optional) – Limit to events with a magnitude larger than the specified minimum.

  • maxmagnitude (float, optional) – Limit to events with a magnitude smaller than the specified maximum.

  • magnitudetype (str, optional) – Specify a magnitude type to use for testing the minimum and maximum limits.

  • eventid (str (or sequence of such), optional) – Select specific event(s) by ID.

  • limit (int, optional) – Limit the results to the specified number of events.

  • offset (int, optional) – Return results starting at the event count specified, starting at 1.

  • contributor (str, optional) – Limit to events contributed by a specified contributor.

  • updatedafter (obspy.UTCDateTime or valid input to such, optional) – Limit to events updated after the specified time.

  • degrees (int, default True) – If False, the parameters maxradius and minradius are specified in m rather than degrees. Note: this parameter may not be supported by non-obsplus event clients.

Return type:

DataFrame

update_index(bar=None, paths=None)[source]

Iterate files in bank and add any modified since last update to index.

Parameters:

  • {bar_parameter_description} –

  • {paths_description} –

Return type:

EventBank