obspy.clients.filesystem.tsindex¶
obspy.clients.filesystem.tsindex - IRIS TSIndex Client and Indexer¶
The obspy.clients.filesystem.tsindex module includes a timeseries extraction Client class for a database created by the IRIS mseedindex program, as well as, a Indexer class for creating a SQLite3 database that follows the IRIS tsindex database schema.
copyright: | Nick Falco, Chad Trabant, IRISDMC, 2018 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 SQLite3 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()
Indexer Usage¶
The Indexer provides a high level API for indexing a directory tree of miniSEED files using the IRIS mseedindex software.
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 IRIS tsindex database schema. |
Indexer | Build an index for miniSEED data using IRIS’s mseedindex program. |
TSIndexDatabaseHandler | Supports direct tsindex database data access and manipulation. |