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, index_path=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 (str | Path | EventBank) – The path to the directory containing event files. If it does not exist an empty directory will be created.

  • path_structure (str | None) –

    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 (str | None) – 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}.

  • index_path (str | Path | None) – The path to the index file containing the contents of the directory. By default it will be created in the top-level of the data directory.

  • 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 (Executor | None) – An executor with the same interface as 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 (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 (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 (ProgressBar | None) –

    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: Use a custom progress bar implementation.

    If a custom progress bar is used, it must have update and finish methods.

  • 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 (ProgressBar | None) –

    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: Use a custom progress bar implementation.

    If a custom progress bar is used, it must have update and finish methods.

  • sub_paths – A str, or iterable of str, specifying subdirectories (relative to bank path) to allow updating only files in specific directories of the bank. This is useful for large banks which have files added to them in predictable locations. However, if other files are added outside of these locations they may not get indexed as the banks timestamp indicating the last time of indexing will still get updated.

Return type:

EventBank