obsplus.EventBank

class obsplus.EventBank(base_path='.', path_structure=None, name_structure=None, format='quakeml', ext='.xml', executor=None)

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.'

__init__(base_path='.', path_structure=None, name_structure=None, format='quakeml', ext='.xml', executor=None)

Initialize an instance.

Methods

__init__([base_path, path_structure, ...])	Initialize an instance.
clear_cache()	Clear the index cache if the bank is using one.
ensure_bank_path_exists([create])	Ensure the bank_path exists else raise an BankDoesNotExistError.
get_event_summary(**kwargs)	Read the index and return a dataframe containing the event info.
get_events(**kwargs)	Read events from bank.
get_progress_bar([bar])	Return a progress bar instance based on bar parameter.
get_service_version()	Return the version of obsplus used to create index.
ids_in_bank(event_id)	Determine if one or more event_ids are used by the bank.
load_example_bank([dataset, path])	Create an example bank which is safe to modify.
put_events(events[, update_index, bar, ...])	Put events into the EventBank.
read_index(**kwargs)	Read the index and return a dataframe containing the event info.
update_index([bar, paths])	Iterate files in bank and add any modified since last update to index.

Attributes

allow_update_timestamp
bank_path
executor
ext
index_name
index_path	Return the expected path to the index file.
last_updated	Get the last time (UTC) that the bank was updated.
last_updated_timestamp	Return the last modified time stored in the index, else 0.0
name_structure
namespace
path_structure