Event Bank

The EventBank class is used to interact with a local directory of event files. The get_events method of Event Bank are compatible with the get_events method of the FDSN client in obspy. Additionally there are several useful features for managing events on disk.

Quickstart

[1]:

import obspy

import obsplus

[2]:

%%capture
# make sure the dataset is downloaded and supress output.
obsplus.load_dataset("crandall_test")

[3]:

# copy the Crandall dataset to a temporary directory
crandall = obsplus.copy_dataset("crandall_test")

# path to directory where events are stored
event_path = crandall.event_path

# init an EventBank instance
bank = obsplus.EventBank(event_path)

# ensure index is up-to-date
bank.update_index()

[3]:

EventBank(base_path=/tmp/tmprg7scu3x/crandall_test/events, index_path=/tmp/tmprg7scu3x/crandall_test/events/.index.db)

Accessing the index

The index can be accessed directly to get a summary of the events contained in the archive. Depending on the task, it may be more natural to work with the index dataframe rather than the obspy catalog objects directly.

[4]:

index = bank.read_index()
index

[4]:
time latitude longitude depth magnitude event_description associated_phase_count azimuthal_gap event_id horizontal_uncertainty ... standard_error used_phase_count station_count vertical_uncertainty updated author agency_id creation_time version path
0 2007-08-06 01:44:48.810 39.4617 -111.2378 6570.0 1.78 LR 0.0 NaN smi:local/248828 NaN ... 0.8936 0.0 23.0 NaN 2025-01-09 18:05:01.310870528 DC NIOSH 2018-10-10 20:26:49.642650 2007/08/06/2007-08-06T01-44-48_48828.xml
1 2007-08-06 10:47:25.600 39.4615 -111.2317 2050.0 1.57 LR 0.0 NaN smi:local/248843 NaN ... 0.8237 0.0 29.0 NaN 2025-01-09 18:05:01.310870528 DC NIOSH 2018-10-10 20:33:27.110914 2007/08/06/2007-08-06T10-47-25_48843.xml
2 2007-08-06 08:48:40.010 39.4635 -111.2277 410.0 4.37 LR 0.0 NaN smi:local/248839 NaN ... 1.7356 0.0 134.0 NaN 2025-01-09 18:05:01.310870528 DC NIOSH 2018-10-10 20:33:13.618111 2007/08/06/2007-08-06T08-48-40_48839.xml
3 2007-08-07 21:42:51.130 39.4627 -111.2200 4620.0 1.65 0.0 NaN smi:local/248925 NaN ... 0.5704 0.0 19.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-11 22:08:54.236916 2007/08/07/2007-08-07T21-42-51_48925.xml
4 2007-08-07 07:13:05.760 39.4605 -111.2242 3240.0 2.24 0.0 NaN smi:local/248891 NaN ... 0.9901 0.0 35.0 NaN 2025-01-09 18:05:01.311870464 NaT 2007/08/07/2007-08-07T07-13-05_48891.xml
5 2007-08-07 02:05:04.490 39.4648 -111.2255 1790.0 2.08 LR 0.0 NaN smi:local/248882 NaN ... 0.9935 0.0 35.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-10 21:15:19.190404 2007/08/07/2007-08-07T02-05-04_48882.xml
6 2007-08-07 02:14:24.080 39.4632 -111.2230 4180.0 1.26 LR 0.0 NaN smi:local/248883 NaN ... 0.8834 0.0 14.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-10 21:10:26.864045 2007/08/07/2007-08-07T02-14-24_48883.xml
7 2007-08-07 03:44:18.470 39.4625 -111.2152 4160.0 1.45 LR 0.0 NaN smi:local/248887 NaN ... 0.5716 0.0 15.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-10 21:10:27.576204 2007/08/07/2007-08-07T03-44-18_48887.xml

8 rows × 28 columns

The index contains the following columns:

[ ]:

If you are working from a data directory that doesn’t have write access, you can specify a custom location for the index path:

[5]:

import tempfile
from pathlib import Path

index_path = Path(tempfile.mkdtemp()) / "index.db"
cust_ind_bank = obsplus.EventBank(event_path, index_path=index_path)
cust_ind_bank.update_index()
ind = cust_ind_bank.read_index()
ind  # Note that paths in the index are relative to event_path

[5]:
time latitude longitude depth magnitude event_description associated_phase_count azimuthal_gap event_id horizontal_uncertainty ... standard_error used_phase_count station_count vertical_uncertainty updated author agency_id creation_time version path
0 2007-08-06 01:44:48.810 39.4617 -111.2378 6570.0 1.78 LR 0.0 NaN smi:local/248828 NaN ... 0.8936 0.0 23.0 NaN 2025-01-09 18:05:01.310870528 DC NIOSH 2018-10-10 20:26:49.642650 2007/08/06/2007-08-06T01-44-48_48828.xml
1 2007-08-06 10:47:25.600 39.4615 -111.2317 2050.0 1.57 LR 0.0 NaN smi:local/248843 NaN ... 0.8237 0.0 29.0 NaN 2025-01-09 18:05:01.310870528 DC NIOSH 2018-10-10 20:33:27.110914 2007/08/06/2007-08-06T10-47-25_48843.xml
2 2007-08-06 08:48:40.010 39.4635 -111.2277 410.0 4.37 LR 0.0 NaN smi:local/248839 NaN ... 1.7356 0.0 134.0 NaN 2025-01-09 18:05:01.310870528 DC NIOSH 2018-10-10 20:33:13.618111 2007/08/06/2007-08-06T08-48-40_48839.xml
3 2007-08-07 21:42:51.130 39.4627 -111.2200 4620.0 1.65 0.0 NaN smi:local/248925 NaN ... 0.5704 0.0 19.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-11 22:08:54.236916 2007/08/07/2007-08-07T21-42-51_48925.xml
4 2007-08-07 07:13:05.760 39.4605 -111.2242 3240.0 2.24 0.0 NaN smi:local/248891 NaN ... 0.9901 0.0 35.0 NaN 2025-01-09 18:05:01.311870464 NaT 2007/08/07/2007-08-07T07-13-05_48891.xml
5 2007-08-07 02:05:04.490 39.4648 -111.2255 1790.0 2.08 LR 0.0 NaN smi:local/248882 NaN ... 0.9935 0.0 35.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-10 21:15:19.190404 2007/08/07/2007-08-07T02-05-04_48882.xml
6 2007-08-07 02:14:24.080 39.4632 -111.2230 4180.0 1.26 LR 0.0 NaN smi:local/248883 NaN ... 0.8834 0.0 14.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-10 21:10:26.864045 2007/08/07/2007-08-07T02-14-24_48883.xml
7 2007-08-07 03:44:18.470 39.4625 -111.2152 4160.0 1.45 LR 0.0 NaN smi:local/248887 NaN ... 0.5716 0.0 15.0 NaN 2025-01-09 18:05:01.311870464 DC NIOSH 2018-10-10 21:10:27.576204 2007/08/07/2007-08-07T03-44-18_48887.xml

8 rows × 28 columns

Get events

The EventBank can be used to get obspy event objects based on query parameters.

[6]:

catalog = bank.get_events(minmagnitude=2)

[ ]:

Put events

Events can be saved to disk using the put_events method. If an event with the same resource_id already exists in the bank it will be overwritten.

[ ]:



[7]:

bank.put_events(obspy.read_events())

[7]:

EventBank(base_path=/tmp/tmprg7scu3x/crandall_test/events, index_path=/tmp/tmprg7scu3x/crandall_test/events/.index.db)

Organizing event directories

EventBank can also be used to (re)organize event directories. The events are saved in the following structure by default: {year/month/day/year-month-dayThour-minute-second-short_id.xml} (where “short_id” means the last 5 characters of the event id).

The structure of the event directories can be reorganized to {year/month/short_id.xml}. The following code demonstrates the process used in changing the event directory structure.

[8]:

import tempfile
from pathlib import Path

temp_dir = Path(tempfile.mkdtemp())

kwargs = dict(
    path_structure="{year}/{month}",
    name_structure="{event_id_short}",
)

[ ]:



[9]:

bank2 = obsplus.EventBank(temp_dir, **kwargs)
bank2.put_events(bank)

[9]:

EventBank(base_path=/tmp/tmp_9so6waz, index_path=/tmp/tmp_9so6waz/.index.db)

Notes

Unlike the WaveBank, which uses HDF5 to index waveforms, EventBank uses a SQLite which is more suitable for frequent updates and CRUD usage patterns.