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¶
-
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
InstaseisDBorRemoteInstaseisDBclasses.- 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
InstaseisDBorRemoteInstaseisDB
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_NAMEwill 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.nc4files are located for example in/path/to/DB/PZ/Dataand/path/to/DB/PX/Data, please pass/path/to/DBto theopen_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.
-
property
available_components¶ Returns a list with all available components.
-
property
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='displacement', return_obspy_stream=True, dt=None, kernelwidth=12, definition='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,REPas defined inMinson, Sarah E., and Douglas S. Dreger (2008)Stable Inversions for Complete Moment Tensors.Geophysical Journal International 174 (2): 585–592.- 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.Streamobject or a dictionary with NumPy arrays as values.
-
get_seismograms(source, receiver, components=None, kind='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.Sourceorinstaseis.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.Streamobject 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.Streamobject or a dictionary with NumPy arrays as values.
-
get_seismograms_finite_source(sources, receiver, components=None, kind='displacement', dt=None, kernelwidth=12, correct_mu=False, progress_callback=None)[source]¶ Extract seismograms for a finite source from an Instaseis database.
- Parameters
sources (
FiniteSourceor list ofSourceobjects.) – 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
-
property
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
db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a
order_output.nc4file.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
db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a
order_output.nc4file.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
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
db_path (str) – Path to the Instaseis Database containing subdirectories PZ and/or PX each containing a
order_output.nc4file.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
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).