Main Instaseis Classes¶

This page documents the central open_db() function and the main Instaseis classes. Please always use the open_db() function to open a connection to an Instaseis database.

open_db() Function
BaseInstaseisDB
BaseNetCDFInstaseisDB
ReciprocalInstaseisDB
ReciprocalMergedInstaseisDB
ForwardInstaseisDB
ForwardMergedInstaseisDB
RemoteInstaseisDB
SyngineInstaseisDB

open_db() Function ¶

instaseis.open_db(path, *args, **kwargs)[source]¶

Central function to open a local or remote Instaseis database. Any keyword arguments are passed to the underlying InstaseisDB or RemoteInstaseisDB classes.

Parameters:	path (str) – Filepath or URL. Instaseis will determine if it is a local file path or a HTTP URL and delegate to the corresponding class.
Returns:	An initialized database object.
Return type:	`InstaseisDB` or `RemoteInstaseisDB`

If a directory is passed, it will return a local Instaseis database:

>>> import instaseis
>>> db = instaseis.open_db("/path/to/DB")  
>>> print(db)  
InstaseisDB reciprocal Green's function Database (v7) generated ...
    components           : vertical and horizontal
    velocity model       : ak135f
    ...

For an HTTP URL it will return a remote Instaseis database:

>>> db = instaseis.open_db("http://webadress.com:8765")  
>>> print(db)  
RemoteInstaseisDB reciprocal Green's function Database (v7) generated ...
    components           : vertical and horizontal
    velocity model       : ak135f

The special syntax syngine://MODEL_NAME will connect to the IRIS syngine web service for the specified model.

>>> db = instaseis.open_db("syngine://ak135f")  
>>> print(db)  
SyngineInstaseisDB reciprocal Green's function Database (v7) ...
Syngine model name:      'ak135f'
Syngine service version:  0.0.2
    components           : vertical and horizontal
    velocity model       : ak135f

Note

If opening a local database and the ordered_output.nc4 files are located for example in /path/to/DB/PZ/Data and /path/to/DB/PX/Data, please pass /path/to/DB to the open_db() function. Instaseis will recursively search the child directories for the necessary files and open them.

BaseInstaseisDB ¶

class instaseis.database_interfaces.base_instaseis_db.BaseInstaseisDB[source]¶

Base class for all Instaseis database classes defining the user interface.

available_components¶: Returns a list with all available components.

default_components¶: The components returned by default by most of the higher level routines.

get_greens_function(epicentral_distance_in_degree, source_depth_in_m, origin_time=UTCDateTime(1970, 1, 1, 0, 0), kind=u'displacement', return_obspy_stream=True, dt=None, kernelwidth=12, definition=u'seiscomp')[source]¶

Extract Green’s function from the Green’s function database.

Currently only one definition is implemented: the one assumed by Seiscomp, i.e. the components TSS, ZSS, RSS, TDS, ZDS, RDS, ZDD, RDD, ZEP, REP as defined in

Minson, Sarah E., and Douglas S. Dreger (2008)
Stable Inversions for Complete Moment Tensors.
Geophysical Journal International 174 (2): 585–592.
http://dx.doi.org/10.1111/j.1365-246X.2008.03797.x

Parameters:	epicentral_distance_in_degree (float) – The epicentral distance in degree. source_depth_in_m (float) – The source depth in m below the surface. origin_time (`obspy.core.utcdatetime.UTCDateTime`) – Origin time of the source. kind (str) – The desired units of the seismogram: `"displacement"`, `"velocity"`, or `"acceleration"`. dt (float) – Desired sampling rate of the Green’s functions. Resampling is done using a Lanczos kernel. kernelwidth (int) – The width of the sinc kernel used for resampling in terms of the original sampling interval. Best choose something between 10 and 20. definition (str) – The desired Green’s function definition.
Returns:	Multi component seismograms.
Return type:	A `obspy.core.stream.Stream` object or a dictionary with NumPy arrays as values.

get_seismograms(source, receiver, components=None, kind=u'displacement', remove_source_shift=True, reconvolve_stf=False, return_obspy_stream=True, dt=None, kernelwidth=12)[source]¶

Extract seismograms from the Green’s function database.

Parameters:	source (`instaseis.source.Source` or `instaseis.source.ForceSource`) – The source definition. receiver (`instaseis.source.Receiver`) – The seismic receiver. components (tuple of str, optional) – Which components to calculate. Must be a tuple containing any combination of `"Z"`, `"N"`, `"E"`, `"R"`, and `"T"`. Defaults to `["Z", "N", "E"]` for two component databases, to `["N", "E"]` for horizontal only databases, and to `["Z"]` for vertical only databases. kind (str, optional) – The desired units of the seismogram: `"displacement"`, `"velocity"`, or `"acceleration"`. remove_source_shift (bool, optional) – Cut all samples before the peak of the source time function. This has the effect that the first sample is the origin time of the source. reconvolve_stf (bool, optional) – Deconvolve the source time function used in the AxiSEM run and convolve with the STF attached to the source. For this to be stable, the new STF needs to bandlimited. return_obspy_stream (bool, optional) – Return format is either an `obspy.core.stream.Stream` object or a dictionary containing the raw NumPy arrays. dt (float, optional) – Desired sampling rate of the seismograms. Resampling is done using a Lanczos kernel. kernelwidth (int, optional) – The width of the sinc kernel used for resampling in terms of the original sampling interval. Best choose something between 10 and 20.
Returns:	Multi component seismograms.
Return type:	A `obspy.core.stream.Stream` object or a dictionary with NumPy arrays as values.

get_seismograms_finite_source(sources, receiver, components=None, kind=u'displacement', dt=None, kernelwidth=12, correct_mu=False, progress_callback=None)[source]¶

Extract seismograms for a finite source from an Instaseis database.

Parameters:	sources (`FiniteSource` or list of `Source` objects.) – A collection of point sources. receiver (`instaseis.source.Receiver`) – The seismic receiver. components (tuple of str, optional) – Which components to calculate. Must be a tuple containing any combination of `"Z"`, `"N"`, `"E"`, `"R"`, and `"T"`. Defaults to `["Z", "N", "E"]` for two component databases, to `["N", "E"]` for horizontal only databases, and to `["Z"]` for vertical only databases. kind (str, optional) – The desired units of the seismogram: `"displacement"`, `"velocity"`, or `"acceleration"`. dt (float, optional) – Desired sampling rate of the seismograms. Resampling is done using a Lanczos kernel. kernelwidth (int, optional) – The width of the sinc kernel used for resampling in terms of the original sampling interval. Best choose something between 10 and 20. correct_mu (bool, optional) – Correct the source magnitude for the actual shear modulus from the model. progress_callback (function, optional) – Optional callback function that will be called with current source number and the number of total sources for each calculated source. Useful for integration into user interfaces to provide some kind of progress information. If the callback returns `True`, the calculation will be cancelled.
Returns:	Multi component finite source seismogram.
Return type:	`obspy.core.stream.Stream`

BaseNetCDFInstaseisDB ¶

class instaseis.database_interfaces.base_netcdf_instaseis_db.BaseNetCDFInstaseisDB(db_path, buffer_size_in_mb=100, read_on_demand=False, *args, **kwargs)[source]¶

Base class for extracting seismograms from a local Instaseis netCDF database.

Parameters:

Parameters:	db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a `order_output.nc4` file. buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent. read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a order_output.nc4 file.
buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent.
read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

ReciprocalInstaseisDB ¶

class instaseis.database_interfaces.reciprocal_instaseis_db.ReciprocalInstaseisDB(db_path, netcdf_files, buffer_size_in_mb=100, read_on_demand=False, *args, **kwargs)[source]¶

Reciprocal Instaseis database.

Parameters:

Parameters:	db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a `order_output.nc4` file. buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent. read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a order_output.nc4 file.
buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent.
read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

ReciprocalMergedInstaseisDB ¶

class instaseis.database_interfaces.reciprocal_merged_instaseis_db.ReciprocalMergedInstaseisDB(db_path, netcdf_file, buffer_size_in_mb=100, read_on_demand=False, *args, **kwargs)[source]¶

Reciprocal Merged Instaseis Database.

Parameters:

Parameters:	db_path (str) – Path to the Instaseis Database. netcdf_file (str) – The path to the actual netcdf4 file. buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent. read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

db_path (str) – Path to the Instaseis Database.
netcdf_file (str) – The path to the actual netcdf4 file.
buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent.
read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

ForwardInstaseisDB ¶

class instaseis.database_interfaces.forward_instaseis_db.ForwardInstaseisDB(db_path, netcdf_files, buffer_size_in_mb=100, read_on_demand=False, *args, **kwargs)[source]¶

Forward Instaseis database.

Parameters:

Parameters:	db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a `order_output.nc4` file. buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent. read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a order_output.nc4 file.
buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent.
read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

ForwardMergedInstaseisDB ¶

class instaseis.database_interfaces.forward_merged_instaseis_db.ForwardMergedInstaseisDB(db_path, netcdf_file, buffer_size_in_mb=100, read_on_demand=False, *args, **kwargs)[source]¶

Merged forward Instaseis database.

Parameters:

Parameters:	db_path (str) – Path to the Instaseis Database. netcdf_file (str) – The path to the actual netcdf4 file. buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent. read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

db_path (str) – Path to the Instaseis Database.
netcdf_file (str) – The path to the actual netcdf4 file.
buffer_size_in_mb (int, optional) – Strain and displacement are buffered to avoid repeated disc access. Depending on the type of database and the number of components of the database, the total buffer memory can be up to four times this number. The optimal value is highly application and system dependent.
read_on_demand (bool, optional) – Read several global fields on demand (faster initialization) or on initialization (slower initialization, faster in individual seismogram extraction, useful e.g. for finite sources, default).

RemoteInstaseisDB ¶

class instaseis.database_interfaces.remote_instaseis_db.RemoteInstaseisDB(url, *args, **kwargs)[source]¶

Remote Instaseis database interface.

Parameters:	url – URL to the remote Instaseis server.

SyngineInstaseisDB ¶

class instaseis.database_interfaces.syngine_instaseis_db.SyngineInstaseisDB(model, base_url=u'http://service.iris.edu/irisws/syngine/1', debug=False, *args, **kwargs)[source]¶

Remote Instaseis interface connecting with IRIS’ syngine service.

Parameters:	model (str) – The model to use. base_url (str) – URL to the root of the syngine service. debug (bool) – Debug messages on/off.