def simulate_seismometer(data,
samp_rate,
paz_remove=None,
paz_simulate=None,
remove_sensitivity=True,
simulate_sensitivity=True,
water_level=600.0,
zero_mean=True,
taper=True,
taper_fraction=0.05,
pre_filt=None,
seedresp=None,
nfft_pow2=False,
pitsasim=True,
sacsim=False,
shsim=False):
"""
Simulate/Correct seismometer.
:type data: NumPy :class:`~numpy.ndarray`
:param data: Seismogram, detrend before hand (e.g. zero mean)
:type samp_rate: float
:param samp_rate: Sample Rate of Seismogram
:type paz_remove: dict, None
:param paz_remove: Dictionary containing keys 'poles', 'zeros', 'gain'
(A0 normalization factor). poles and zeros must be a list of complex
floating point numbers, gain must be of type float. Poles and Zeros are
assumed to correct to m/s, SEED convention. Use None for no inverse
filtering.
:type paz_simulate: dict, None
:param paz_simulate: Dictionary containing keys 'poles', 'zeros', 'gain'.
Poles and zeros must be a list of complex floating point numbers, gain
must be of type float. Or None for no simulation.
:type remove_sensitivity: bool
:param remove_sensitivity: Determines if data is divided by
`paz_remove['sensitivity']` to correct for overall sensitivity of
recording instrument (seismometer/digitizer) during instrument
correction.
:type simulate_sensitivity: bool
:param simulate_sensitivity: Determines if data is multiplied with
`paz_simulate['sensitivity']` to simulate overall sensitivity of
new instrument (seismometer/digitizer) during instrument simulation.
:type water_level: float
:param water_level: Water_Level for spectrum to simulate
:type zero_mean: bool
:param zero_mean: If true the mean of the data is subtracted
:type taper: bool
:param taper: If true a cosine taper is applied.
:type taper_fraction: float
:param taper_fraction: Taper fraction of cosine taper to use
:type pre_filt: list or tuple of floats
:param pre_filt: Apply a bandpass filter to the data trace before
deconvolution. The list or tuple defines the four corner frequencies
(f1,f2,f3,f4) of a cosine taper which is one between f2 and f3 and
tapers to zero for f1 < f < f2 and f3 < f < f4.
:type seedresp: dict, None
:param seedresp: Dictionary contains keys 'filename', 'date', 'units'.
'filename' is the path to a RESP-file generated from a dataless SEED
volume (or a file like object with RESP information);
'date' is a :class:`~obspy.core.utcdatetime.UTCDateTime` object for the
date that the response function should be extracted for (can be omitted
when calling simulate() on Trace/Stream. the Trace's starttime will
then be used);
'units' defines the units of the response function.
Can be either 'DIS', 'VEL' or 'ACC'.
:type nfft_pow2: bool
:param nfft_pow2: Number of frequency points to use for FFT. If True,
the exact power of two is taken (default in PITSA). If False the
data are not zero-padded to the next power of two which makes a
slower FFT but is then much faster for e.g. evalresp which scales
with the FFT points.
:type pitsasim: bool
:param pitsasim: Choose parameters to match
instrument correction as done by PITSA.
:type sacsim: bool
:param sacsim: Choose parameters to match
instrument correction as done by SAC.
:type shsim: bool
:param shsim: Choose parameters to match
instrument correction as done by Seismic Handler.
:return: The corrected data are returned as :class:`numpy.ndarray` float64
array. float64 is chosen to avoid numerical instabilities.
This function works in the frequency domain, where nfft is the next power
of len(data) to avoid wrap around effects during convolution. The inverse
of the frequency response of the seismometer (``paz_remove``) is
convolved with the spectrum of the data and with the frequency response
of the seismometer to simulate (``paz_simulate``). A 5% cosine taper is
taken before simulation. The data must be detrended (e.g.) zero mean
beforehand. If paz_simulate=None only the instrument correction is done.
In the latter case, a broadband filter can be applied to the data trace
using pre_filt. This restricts the signal to the valid frequency band and
thereby avoids artifacts due to amplification of frequencies outside of the
instrument's passband (for a detailed discussion see
*Of Poles and Zeros*, F. Scherbaum, Kluwer Academic Publishers).
.. versionchanged:: 0.5.1
The default for `remove_sensitivity` and `simulate_sensitivity` has
been changed to ``True``. Old deprecated keyword arguments `paz`,
`inst_sim`, `no_inverse_filtering` have been removed.
"""
# Checking the types
if not paz_remove and not paz_simulate and not seedresp:
msg = "Neither inverse nor forward instrument simulation specified."
raise TypeError(msg)
for d in [paz_remove, paz_simulate]:
if d is None:
continue
for key in ['poles', 'zeros', 'gain']:
if key not in d:
raise KeyError("Missing key: %s" % key)
# Translated from PITSA: spr_resg.c
delta = 1.0 / samp_rate
#
ndat = len(data)
data = data.astype(np.float64)
if zero_mean:
data -= data.mean()
if taper:
if sacsim:
data *= cosine_taper(ndat,
taper_fraction,
sactaper=sacsim,
halfcosine=False)
else:
data *= cosine_taper(ndat, taper_fraction)
# The number of points for the FFT has to be at least 2 * ndat (in
# order to prohibit wrap around effects during convolution) cf.
# Numerical Recipes p. 429 calculate next power of 2.
if nfft_pow2:
nfft = util.next_pow_2(2 * ndat)
# evalresp scales directly with nfft, therefore taking the next power of
# two has a greater negative performance impact than the slow down of a
# not power of two in the FFT
else:
nfft = _npts2nfft(ndat)
# Transform data in Fourier domain
data = np.fft.rfft(data, n=nfft)
# Inverse filtering = Instrument correction
if paz_remove:
freq_response, freqs = paz_to_freq_resp(paz_remove['poles'],
paz_remove['zeros'],
paz_remove['gain'],
delta,
nfft,
freq=True)
if seedresp:
freq_response, freqs = evalresp(delta,
nfft,
seedresp['filename'],
seedresp['date'],
units=seedresp['units'],
freq=True,
network=seedresp['network'],
station=seedresp['station'],
locid=seedresp['location'],
channel=seedresp['channel'])
if not remove_sensitivity:
msg = "remove_sensitivity is set to False, but since seedresp " + \
"is selected the overall sensitivity will be corrected " + \
" for anyway!"
warnings.warn(msg)
if paz_remove or seedresp:
if pre_filt:
# make cosine taper
fl1, fl2, fl3, fl4 = pre_filt
if sacsim:
cos_win = cosine_sac_taper(freqs, flimit=(fl1, fl2, fl3, fl4))
else:
cos_win = cosine_taper(freqs.size,
freqs=freqs,
flimit=(fl1, fl2, fl3, fl4))
data *= cos_win
invert_spectrum(freq_response, water_level)
data *= freq_response
del freq_response
# Forward filtering = Instrument simulation
if paz_simulate:
data *= paz_to_freq_resp(paz_simulate['poles'], paz_simulate['zeros'],
paz_simulate['gain'], delta, nfft)
data[-1] = abs(data[-1]) + 0.0j
# transform data back into the time domain
data = np.fft.irfft(data)[0:ndat]
if pitsasim:
# linear detrend
data = simple_detrend(data)
if shsim:
# detrend using least squares
data = scipy.signal.detrend(data, type="linear")
# correct for involved overall sensitivities
if paz_remove and remove_sensitivity and not seedresp:
data /= paz_remove['sensitivity']
if paz_simulate and simulate_sensitivity:
data *= paz_simulate['sensitivity']
return data
def simulate_seismometer(
data, samp_rate, paz_remove=None, paz_simulate=None,
remove_sensitivity=True, simulate_sensitivity=True, water_level=600.0,
zero_mean=True, taper=True, taper_fraction=0.05, pre_filt=None,
seedresp=None, nfft_pow2=False, pitsasim=True, sacsim=False,
shsim=False):
"""
Simulate/Correct seismometer.
:type data: NumPy :class:`~numpy.ndarray`
:param data: Seismogram, detrend before hand (e.g. zero mean)
:type samp_rate: float
:param samp_rate: Sample Rate of Seismogram
:type paz_remove: dict, None
:param paz_remove: Dictionary containing keys 'poles', 'zeros', 'gain'
(A0 normalization factor). poles and zeros must be a list of complex
floating point numbers, gain must be of type float. Poles and Zeros are
assumed to correct to m/s, SEED convention. Use None for no inverse
filtering.
:type paz_simulate: dict, None
:param paz_simulate: Dictionary containing keys 'poles', 'zeros', 'gain'.
Poles and zeros must be a list of complex floating point numbers, gain
must be of type float. Or None for no simulation.
:type remove_sensitivity: bool
:param remove_sensitivity: Determines if data is divided by
`paz_remove['sensitivity']` to correct for overall sensitivity of
recording instrument (seismometer/digitizer) during instrument
correction.
:type simulate_sensitivity: bool
:param simulate_sensitivity: Determines if data is multiplied with
`paz_simulate['sensitivity']` to simulate overall sensitivity of
new instrument (seismometer/digitizer) during instrument simulation.
:type water_level: float
:param water_level: Water_Level for spectrum to simulate
:type zero_mean: bool
:param zero_mean: If true the mean of the data is subtracted
:type taper: bool
:param taper: If true a cosine taper is applied.
:type taper_fraction: float
:param taper_fraction: Taper fraction of cosine taper to use
:type pre_filt: list or tuple of floats
:param pre_filt: Apply a bandpass filter to the data trace before
deconvolution. The list or tuple defines the four corner frequencies
(f1,f2,f3,f4) of a cosine taper which is one between f2 and f3 and
tapers to zero for f1 < f < f2 and f3 < f < f4.
:type seedresp: dict, None
:param seedresp: Dictionary contains keys 'filename', 'date', 'units'.
'filename' is the path to a RESP-file generated from a dataless SEED
volume (or a file like object with RESP information);
'date' is a :class:`~obspy.core.utcdatetime.UTCDateTime` object for the
date that the response function should be extracted for (can be omitted
when calling simulate() on Trace/Stream. the Trace's starttime will
then be used);
'units' defines the units of the response function.
Can be either 'DIS', 'VEL' or 'ACC'.
:type nfft_pow2: bool
:param nfft_pow2: Number of frequency points to use for FFT. If True,
the exact power of two is taken (default in PITSA). If False the
data are not zero-padded to the next power of two which makes a
slower FFT but is then much faster for e.g. evalresp which scales
with the FFT points.
:type pitsasim: bool
:param pitsasim: Choose parameters to match
instrument correction as done by PITSA.
:type sacsim: bool
:param sacsim: Choose parameters to match
instrument correction as done by SAC.
:type shsim: bool
:param shsim: Choose parameters to match
instrument correction as done by Seismic Handler.
:return: The corrected data are returned as :class:`numpy.ndarray` float64
array. float64 is chosen to avoid numerical instabilities.
This function works in the frequency domain, where nfft is the next power
of len(data) to avoid wrap around effects during convolution. The inverse
of the frequency response of the seismometer (``paz_remove``) is
convolved with the spectrum of the data and with the frequency response
of the seismometer to simulate (``paz_simulate``). A 5% cosine taper is
taken before simulation. The data must be detrended (e.g.) zero mean
beforehand. If paz_simulate=None only the instrument correction is done.
In the latter case, a broadband filter can be applied to the data trace
using pre_filt. This restricts the signal to the valid frequency band and
thereby avoids artifacts due to amplification of frequencies outside of the
instrument's passband (for a detailed discussion see
*Of Poles and Zeros*, F. Scherbaum, Kluwer Academic Publishers).
.. versionchanged:: 0.5.1
The default for `remove_sensitivity` and `simulate_sensitivity` has
been changed to ``True``. Old deprecated keyword arguments `paz`,
`inst_sim`, `no_inverse_filtering` have been removed.
"""
# Checking the types
if not paz_remove and not paz_simulate and not seedresp:
msg = "Neither inverse nor forward instrument simulation specified."
raise TypeError(msg)
for d in [paz_remove, paz_simulate]:
if d is None:
continue
for key in ['poles', 'zeros', 'gain']:
if key not in d:
raise KeyError("Missing key: %s" % key)
# Translated from PITSA: spr_resg.c
delta = 1.0 / samp_rate
#
ndat = len(data)
data = data.astype(np.float64)
if zero_mean:
data -= data.mean()
if taper:
if sacsim:
data *= cosine_taper(ndat, taper_fraction,
sactaper=sacsim, halfcosine=False)
else:
data *= cosine_taper(ndat, taper_fraction)
# The number of points for the FFT has to be at least 2 * ndat (in
# order to prohibit wrap around effects during convolution) cf.
# Numerical Recipes p. 429 calculate next power of 2.
if nfft_pow2:
nfft = util.next_pow_2(2 * ndat)
# evalresp scales directly with nfft, therefore taking the next power of
# two has a greater negative performance impact than the slow down of a
# not power of two in the FFT
else:
nfft = _npts2nfft(ndat)
# Transform data in Fourier domain
data = np.fft.rfft(data, n=nfft)
# Inverse filtering = Instrument correction
if paz_remove:
freq_response, freqs = paz_to_freq_resp(
paz_remove['poles'], paz_remove['zeros'], paz_remove['gain'],
delta, nfft, freq=True)
if seedresp:
freq_response, freqs = evalresp(delta, nfft, seedresp['filename'],
seedresp['date'],
units=seedresp['units'], freq=True,
network=seedresp['network'],
station=seedresp['station'],
locid=seedresp['location'],
channel=seedresp['channel'])
if not remove_sensitivity:
msg = "remove_sensitivity is set to False, but since seedresp " + \
"is selected the overall sensitivity will be corrected " + \
" for anyway!"
warnings.warn(msg)
if paz_remove or seedresp:
if pre_filt:
# make cosine taper
fl1, fl2, fl3, fl4 = pre_filt
if sacsim:
cos_win = cosine_sac_taper(freqs, flimit=(fl1, fl2, fl3, fl4))
else:
cos_win = cosine_taper(freqs.size, freqs=freqs,
flimit=(fl1, fl2, fl3, fl4))
data *= cos_win
invert_spectrum(freq_response, water_level)
data *= freq_response
del freq_response
# Forward filtering = Instrument simulation
if paz_simulate:
data *= paz_to_freq_resp(paz_simulate['poles'], paz_simulate['zeros'],
paz_simulate['gain'], delta, nfft)
data[-1] = abs(data[-1]) + 0.0j
# transform data back into the time domain
data = np.fft.irfft(data)[0:ndat]
if pitsasim:
# linear detrend
data = simple_detrend(data)
if shsim:
# detrend using least squares
data = scipy.signal.detrend(data, type="linear")
# correct for involved overall sensitivities
if paz_remove and remove_sensitivity and not seedresp:
data /= paz_remove['sensitivity']
if paz_simulate and simulate_sensitivity:
data *= paz_simulate['sensitivity']
return data