obspy.clients.filesystem.tsindex

obspy.clients.filesystem.tsindex - EarthScope TSIndex Client and Indexer

The obspy.clients.filesystem.tsindex module includes a timeseries extraction Client class for a database created by the EarthScope mseedindex program, as well as, a Indexer class to create a SQLite3 database, following the EarthScope tsindex database schema.

copyright:: Nick Falco, Chad Trabant, EarthScope (former IRIS) Data Services, 2024 The ObsPy Development Team (devs@obspy.org)
license:: GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

Client Usage 

The first step is always to initialize a client object.

>>> from obspy.clients.filesystem.tsindex import Client
>>> from obspy.clients.filesystem.tests.test_tsindex \
...     import get_test_data_filepath
>>> import os
>>> # for this example get the file path to test data
>>> filepath = get_test_data_filepath()
>>> db_path = os.path.join(filepath, 'timeseries.sqlite')
>>> # create a new Client instance
>>> client = Client(db_path, datapath_replace=("^", filepath))

The example below uses the test SQLite tsindex database included with ObsPy to illustrate how to do the following:

Determine what data is available in the tsindex database using get_availability_extent() and get_availability(), as well as, the percentage of data available using get_availability_percentage().
Request available timeseries data using get_waveforms() and get_waveforms_bulk().

Determining Data Availability 

get_availability_extent(): Returns a list of (network, station, location, channel, earliest, latest) tuples that represent the full extent of available data. This example retrieves from the very small obspy test tsindex database a list of all available (“BHZ”) channel extents from the Global Seismograph Network (“IU”) for all times.

>>> extents = client.get_availability_extent(network="IU", channel="BHZ")
>>> for extent in extents:
...     print("{0:<3} {1:<6} {2:<3} {3:<4} {4} {5}".format(*extent))
IU  ANMO   10  BHZ  2018-01-01T00:00:00.019500Z 2018-01-01T00:00:59.994536Z
IU  COLA   10  BHZ  2018-01-01T00:00:00.019500Z 2018-01-01T00:00:59.994538Z

get_availability(): Works in the same way as get_availability_extent() but returns a list of (network, station, location, channel, starttime, endtime) tuples representing contiguous time spans for selected channels and time ranges.
get_availability_percentage(): Returns the tuple(float, int) of percentage of available data (0.0 to 1.0) and number of gaps/overlaps. Availability percentage is calculated relative to the provided starttime and endtime.

>>> from obspy import UTCDateTime
>>> avail_percentage = client.get_availability_percentage(
...     "IU", "ANMO", "10", "BHZ",
...     UTCDateTime(2018, 1, 1, 0, 0, 0, 19500),
...     UTCDateTime(2018, 1, 1, 0, 1, 57, 994536))
>>> print(avail_percentage)
(0.5083705674817509, 1)

Requesting Timeseries Data 

get_waveforms(): This example illustrates how to request 1 second of available (“IU”) timeseries data in the test tsindex database. Results are returned as a Stream object. See the get_waveforms_bulk() method for information on how to make multiple requests at once.

>>> t = UTCDateTime("2018-01-01T00:00:00.019500")
>>> st = client.get_waveforms("IU", "*", "*", "BHZ", t, t + 1)
>>> st.plot()  

(Source code)

Indexer Usage 

The Indexer provides a high level API for indexing a directory tree of miniSEED files using the EarthScope mseedindex software.

An important feature of this module is the ability to index data files in parallel, making it convenient for indexing large data sets of many files.

Initialize an indexer object by supplying the root path to data to be indexed.

>>> from obspy.clients.filesystem.tsindex import Indexer
>>> from obspy.clients.filesystem.tests.test_tsindex \
...     import get_test_data_filepath
>>> # for this example get the file path to test data
>>> filepath = get_test_data_filepath()
>>> # create a new Indexer instance
>>> indexer = Indexer(filepath, filename_pattern='*.mseed')

Index a directory tree of miniSEED files by calling run(). By default this will create a database called timeseries.sqlite in the current working directory. The name of the index database can be changed by supplying the database parameter when instantiating the Indexer object.

indexer.run()

Private Functions

Warning

Private functions are mainly for internal/developer use and their API might change without notice.

_pickle_method

Allows serializing of class and instance methods.

Classes

`Client`	Time series extraction client for EarthScope tsindex database schema.
`Indexer`	Build an index for miniSEED data using EarthScope's mseedindex program.
`TSIndexDatabaseHandler`	Supports direct tsindex database data access and manipulation.

obspy.clients.filesystem.tsindex