MouseTrap is an opensource module for Python for detecting a special type of disturbance (so called mouse, ping, or fling step) in seismic records.
The code is described in paper Vackář et al., Seis. Res. Lett., 2015 (link, PDF)
Please support the project by acknowledging the use of it. If you use MouseTrap for work resulting in an academic publication, we would be grateful if the following paper is cited:
Initialize class mouse. For using with default configuration, simply type:
my_mouse = mouse()
Calculates the instrument output for a given transfer function and a unit acceleration (variantly velocity or displacement) step on the input.
The transfer function is given by paz, which might come from ObsPy function sac.sacio.attach_paz or arclink.client.Client.getPAZ. The calculated time series has a length of length, which should be a power of 2, otherwise it is increased to next power of 2. Parameter dt specifies time interval between following two time samples. The step is placed onset seconds after the record start time. The input is velocity step for typ=2, displacement step for typ=3, and acceleration step for typ=1 or any other value (default). If the demean and integrate parameters are True, the functions mouse.demean() and mouse.integrate() are applied on the result, respectively. If the parameter integrate=True, the result, saved in the variable mouse.mouse, is displacement time series; integrate=False results in velocity time series.
Removes the mean value of the interval before mouse onset from entire synthetic mouse record.
Typically, it is not necessary to run it separately, it is called from mouse.create().
Integrates the synthetic mouse record by rectangular rule.
Typically, it is not necessary to run it separately, it is called from mouse.create().
Fits a given threecomponent or onecomponent record by the synthetic mouse.
Synthetic mouse must be calculated before by mouse.create(). For threecomponent inversion, st is ObsPy stream object, which must contain three components with channels (st[i].stats.channel) named ??N, ??E, and ??Z (e.g. HHN, HHE, and HHZ). For onecomponent inversion, st is ObsPy trace object.
Parameters t_min and t_max affect the gridsearch over time. If they are nonzero, they declares first and last tested time of mouse onset (in seconds from stream starttime). If t_min=0 and t_max=0, the first and last tested time is starttime and endtime of the record, respectively.
Analytically calculates bestfit mouse direction and amplitude based on partial derivatives (see Section Formulas behind).
It is called from mouse.fit_3D(), no need for using it alone.
Analytically calculates bestfit mouse amplitude based on partial derivatives in case of onecomponent inversion. It is simplified version of mouse.invert().
It is called from mouse.fit_3D(), no need for using it alone.
Distinguishes whether the mouse is present according the fit value and the difference between the mouse onset time and Swave arrival time. The output is 2 if the mouse is present, 0 is the mouse is not present, and 1 if it is case in the middle of the way. Variantly, the output can be mouse likelihood value (see below).
Parameters: 


Remark: Function uses some empirical constants chosen for one study. If you need to decide obaut mouse presence or absence, think about your own criterion based on amplitude and fit values and possibly time of the onset.
Parameters:  degrees (bool, optional) – return angles in degrees instead of radians 

Returns tuple of the parameters and fit of the detected mouse: onset (second), amplitude ( for mouse type 1), azimuth (radians, optionaly degrees), inclination (radians, optionaly degrees), and fit (percent). If the angles were not inverted (in case of onecomponent inversion), returns None value for them, so the order of returned tuple does not change.
Plots the comparison between observed record (st) and synthetic mouse with fitted onset, amplitude and direction, so the function mouse.fit_3D() must be called first.
If outfile is specified, the figure is saved to this file, otherwise it is displayed on the screen. The parameter distance specifies the vertical distance between three traces in the figure (in the same units as the traces are). ylabel specifies the yaxis label, xmin and xmax range of x axis, legend turns on legend in the plot. yaxes turns on ticks and values on the yaxis and add y2axis showing acceleration of the simulated step.
Analyses the signaltonoise ratio of the record, removes the beforeevent mean value and integrates record into displacement.
It is shorthand for
if NoiseTest1_demean(st, t, ratio_velocity):
return 'Record too noisy.'
ToDisplacement(st, bitrate)
if NoiseTest2(st, t, ratio_displacement):
return 'Record too noisy after integration.'
Removes the beforeevent mean value from entire st stream. The beforeevent interval is specified by t parameter in seconds from starttime of the stream.
Then it tests simple signaltonoise criterion. The ratio of beforeeventmaximum must be ratio times smaller than the record maximum. If the stream does not pass this test, the function returns True.
Calculates mean value from part of the records between starttime and the time t and removes this mean from entire stream st.
Integrates and downsamples the record st to given bitrate.
Test simple signaltonoise criterion. The ratio of beforeeventmaximum must be ratio times smaller than the record maximum. If the stream does not pass this test, the function returns True.
The synthetic mouse (forward modeling) in raw velocity is described by
where is an impulse response of the instrument to input velocity and is the input unit acceleration step, i.e. the Heaviside function ( for and for ). The mouse in displacement is then
We use 4 parameters for description of a real mouse: time of the onset of the acceleration step, amplitude of the acceleration step and two spatial angles – horizontal azimuth of acceleration pulse and its inclination from the horizontal plane. The east, north and vertical component of the displacement record are then
Fitting a record by the synthetic mouse formally means solving inverse problem with 4 parameters: , , , and . The inverse problem is solved by the leastsquares method (LSQ) to minimize the norm difference between the observed record and synthetic mouse, assuming a value of . Analytical expressions of the partial derivatives with respect to , , and are used in the LSQ fitting. The proper value of is calculated by grid search. The fit is quantified by variance reduction (VR).
Let have a three component record with northsouth, eastwest, and vertical components , , and , respectively, where index time samples. We want to minimize the difference between the record and a synthetic disturbance by finding proper amplitude , azimuth , and inclination of the disturbance. The difference in the norm should be minimal
so its partial derivatives should be zero. From we get
From we get
From we get
To start using MouseTrap, type:
from MouseTrap import *
To create synthetic mouse, we need poles and zeros for some instrument:
from obspy.core import AttribDict
paz = AttribDict({
'sensitivity': 600000000.0,
'poles': [(0.1103+0.111j), (0.11030.111j), (86.3+0j), (241+178j), (241178j), (535+719j), (535719j)],
'gain': 110400.0,
'zeros': [0j, 0j, (68.8+0j), (323+0j), (2530+0j)]
})
Now, we can create synthetic a mouse:
m1 = mouse()
m1.create(paz, 4000, 0.1, 100, 1)
The m1 mouse has 4000 samples at sampling rate 0.1 second and the mouse onset is at time 100 second.
Finally, lets plot the result:
import matplotlib.pyplot as plt
t = np.arange(0, len(m1.mouse)/10., 0.1)
plt.plot(t,m1.mouse)
plt.show()
You can download source codes of some examples in Section Download.
Example of use MouseTrap module for a massive detection of disturbances in a large dataset using SeisComP database.
For description, see flowchart of the algorithm and paper mentioned in section Acknowledging.