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:
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).