marcel/pylot
3
0
Fork 0
Code Issues 7 Pull Requests 1 Releases Wiki Activity

[change] docstrings in pick/utils.py

Browse Source
This commit is contained in:
Darius Arnold 2017-10-16 21:04:37 +02:00
parent fab1f53a41
commit a5b3c5da1b
1 changed files with 216 additions and 192 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

404
pylot/core/pick/utils.py
View File

@ -16,28 +16,34 @@ from obspy.core import Stream, UTCDateTime
def earllatepicker(X, nfac, TSNR, Pick1, iplot=0, verbosity=1, fig=None, linecolor='k'): def earllatepicker(X, nfac, TSNR, Pick1, iplot=0, verbosity=1, fig=None, linecolor='k'):
''' """
Function to derive earliest and latest possible pick after Diehl & Kissling (2009) Function to derive earliest and latest possible pick after Diehl & Kissling (2009)
as reasonable uncertainties. Latest possible pick is based on noise level, as reasonable uncertainties. Latest possible pick is based on noise level,
earliest possible pick is half a signal wavelength in front of most likely earliest possible pick is half a signal wavelength in front of most likely
pick given by PragPicker or manually set by analyst. Most likely pick pick given by PragPicker or manually set by analyst. Most likely pick
(initial pick Pick1) must be given. (initial pick Pick1) must be given.
:param X: time series (seismogram)
:param: X, time series (seismogram) :type X: `~obspy.core.stream.Stream`
:type: `~obspy.core.stream.Stream` :param nfac: (noise factor), nfac times noise level to calculate latest possible pick
:type nfac: int
:param: nfac (noise factor), nfac times noise level to calculate latest possible pick :param TSNR: length of time windows around pick used to determine SNR [s]
:type: int :type TSNR: tuple (T_noise, T_gap, T_signal)
:param Pick1: initial (most likely) onset time, starting point for earllatepicker
:param: TSNR, length of time windows around pick used to determine SNR [s] :type Pick1: float
:type: tuple (T_noise, T_gap, T_signal) :param iplot: if given, results are plotted in figure(iplot)
:type iplot: int
:param: Pick1, initial (most likely) onset time, starting point for earllatepicker :param verbosity: amount of displayed information about the process:
:type: float 2 = all
1 = default
:param: iplot, if given, results are plotted in figure(iplot) 0 = none
:type: int :type verbosity: int
''' :param fig: Matplotlib figure ised for plotting
:type fig: `~matplotlib.figure.Figure`
:param linecolor: color for plotting results
:type linecolor: str
:return: tuple containing earliest possible pick, latest possible pick and pick error
:rtype: (float, float, float)
"""
assert isinstance(X, Stream), "%s is not a stream object" % str(X) assert isinstance(X, Stream), "%s is not a stream object" % str(X)
@ -162,26 +168,27 @@ def earllatepicker(X, nfac, TSNR, Pick1, iplot=0, verbosity=1, fig=None, linecol
def fmpicker(Xraw, Xfilt, pickwin, Pick, iplot=0, fig=None, linecolor='k'): def fmpicker(Xraw, Xfilt, pickwin, Pick, iplot=0, fig=None, linecolor='k'):
''' """
Function to derive first motion (polarity) of given phase onset Pick. Function to derive first motion (polarity) of given phase onset Pick.
Calculation is based on zero crossings determined within time window pickwin Calculation is based on zero crossings determined within time window pickwin
after given onset time. after given onset time.
:param Xraw: unfiltered time series (seismogram)
:param: Xraw, unfiltered time series (seismogram) :type Xraw: `~obspy.core.stream.Stream`
:type: `~obspy.core.stream.Stream` :param Xfilt: filtered time series (seismogram)
:type Xfilt: `~obspy.core.stream.Stream`
:param: Xfilt, filtered time series (seismogram) :param pickwin: time window after onset Pick within zero crossings are calculated
:type: `~obspy.core.stream.Stream` :type pickwin: float
:param Pick: initial (most likely) onset time, starting point for fmpicker
:param: pickwin, time window after onset Pick within zero crossings are calculated :type Pick: float
:type: float :param iplot: if given, results are plotted in figure(iplot)
:type iplot: int
:param: Pick, initial (most likely) onset time, starting point for fmpicker :param fig: Matplotlib figure ised for plotting
:type: float :type fig: `~matplotlib.figure.Figure`
:param linecolor: color for plotting results
:param: iplot, if given, results are plotted in figure(iplot) :type linecolor: str
:type: int :return: None if first motion detection was skipped, otherwise string indicating the polarity
''' :rtype: None, str
"""
plt_flag = 0 plt_flag = 0
try: try:
@ -360,8 +367,15 @@ def fmpicker(Xraw, Xfilt, pickwin, Pick, iplot=0, fig=None, linecolor='k'):
def crossings_nonzero_all(data): def crossings_nonzero_all(data):
"""
Returns the indices of zero crossings the data array
:param data: data array (seismic trace)
:type data: `~numpy.ndarray`
:return: array containing indices of zero crossings in the data array.
:rtype: `~numpy.ndarray`
"""
pos = data > 0 pos = data > 0
npos = ~pos npos = ~pos # get positions of negative values
return ((pos[:-1] & npos[1:]) | (npos[:-1] & pos[1:])).nonzero()[0] return ((pos[:-1] & npos[1:]) | (npos[:-1] & pos[1:])).nonzero()[0]
@ -372,26 +386,28 @@ def symmetrize_error(dte, dtl):
:param dte: relative lower uncertainty :param dte: relative lower uncertainty
:param dtl: relative upper uncertainty :param dtl: relative upper uncertainty
:return: symmetrized error :return: symmetrized error
:rtype: float
""" """
return (dte + 2 * dtl) / 3 return (dte + 2 * dtl) / 3
def getSNR(X, TSNR, t1, tracenum=0): def getSNR(X, TSNR, t1, tracenum=0):
''' """
Function to calculate SNR of certain part of seismogram relative to Function to calculate SNR of certain part of seismogram relative to
given time (onset) out of given noise and signal windows. A safety gap given time (onset) out of given noise and signal windows. A safety gap
between noise and signal part can be set. Returns SNR and SNR [dB] and between noise and signal part can be set. Returns SNR and SNR [dB] and
noiselevel. noiselevel.
:param X: time series (seismogram)
:param: X, time series (seismogram) :type X: `~obspy.core.stream.Stream`
:type: `~obspy.core.stream.Stream` :param TSNR: length of time windows [s] around t1 (onset) used to determine SNR
:type TSNR: (T_noise, T_gap, T_signal)
:param: TSNR, length of time windows [s] around t1 (onset) used to determine SNR :param t1: initial time (onset) from which noise and signal windows are calculated
:type: tuple (T_noise, T_gap, T_signal) :type t1: float
:param tracenum: used to select the trace in stream X
:param: t1, initial time (onset) from which noise and signal windows are calculated :type tracenum: int
:type: float :return: tuple containing SNR, SNRdB and noise level
''' :rtype: (float, float, float)
"""
assert isinstance(X, Stream), "%s is not a stream object" % str(X) assert isinstance(X, Stream), "%s is not a stream object" % str(X)
@ -435,23 +451,21 @@ def getSNR(X, TSNR, t1, tracenum=0):
def getnoisewin(t, t1, tnoise, tgap): def getnoisewin(t, t1, tnoise, tgap):
''' """
Function to extract indeces of data out of time series for noise calculation. Function to extract indices of data out of time series for noise calculation.
Returns an array of indeces. Returns an array of indices.
:param t: array of time stamps
:param: t, array of time stamps :type t: `numpy.ndarray`
:type: numpy array :param t1: time from which relative to it noise window is extracted
:type t1: float
:param: t1, time from which relativ to it noise window is extracted :param tnoise: length of time window [s] for noise part extraction
:type: float :type tnoise: float
:param tgap: safety gap between t1 (onset) and noise window to ensure, that
:param: tnoise, length of time window [s] for noise part extraction the noise window contains no signal
:type: float :type tgap: float
:return: indices of noise window in t
:param: tgap, safety gap between t1 (onset) and noise window to :rtype: `~numpy.ndarray`
ensure, that noise window contains no signal """
:type: float
'''
# get noise window # get noise window
inoise, = np.where((t <= max([t1 - tgap, 0])) \ inoise, = np.where((t <= max([t1 - tgap, 0])) \
@ -465,19 +479,18 @@ def getnoisewin(t, t1, tnoise, tgap):
def getsignalwin(t, t1, tsignal): def getsignalwin(t, t1, tsignal):
''' """
Function to extract data out of time series for signal level calculation. Function to extract data out of time series for signal level calculation.
Returns an array of indeces. Returns an array of indices.
:param t: array of time stamps
:param: t, array of time stamps :type t: `numpy.ndarray`
:type: numpy array :param t1: time from which relative to it signal window is extracted
:type t1: float
:param: t1, time from which relativ to it signal window is extracted :param tsignal: length of time window [s] for signal level calculation
:type: float :type tsignal: float
:return: indices of signal window i t
:param: tsignal, length of time window [s] for signal level calculation :rtype: `numpy.ndarray`
:type: float """
'''
# get signal window # get signal window
isignal, = np.where((t <= min([t1 + tsignal, t[-1]])) \ isignal, = np.where((t <= min([t1 + tsignal, t[-1]])) \
@ -490,27 +503,18 @@ def getsignalwin(t, t1, tsignal):
def getResolutionWindow(snr, extent): def getResolutionWindow(snr, extent):
""" """
Number -> Float Produce the half of the time resolution window width from given SNR value
produce the half of the time resolution window width from given SNR
value
SNR >= 3 -> 2 sec HRW SNR >= 3 -> 2 sec HRW
3 > SNR >= 2 -> 5 sec MRW 3 > SNR >= 2 -> 5 sec MRW
2 > SNR >= 1.5 -> 10 sec LRW 2 > SNR >= 1.5 -> 10 sec LRW
1.5 > SNR -> 15 sec VLRW 1.5 > SNR -> 15 sec VLRW
see also Diehl et al. 2009 see also Diehl et al. 2009
:param snr: Signal to noise ration which decides the witdth of the resolution window
:parameter: extent, can be 'local', 'regional', 'global' :type snr: float
:param extent: can be 'local', 'regional', 'global'
>>> getResolutionWindow(0.5) :type extent: str
7.5 :return: half width of the resolution window
>>> getResolutionWindow(1.8) :rtype: float
5.0
>>> getResolutionWindow(2.3)
2.5
>>> getResolutionWindow(4)
1.0
>>> getResolutionWindow(2)
2.5
""" """
res_wins = { res_wins = {
@ -535,17 +539,17 @@ def getResolutionWindow(snr, extent):
def select_for_phase(st, phase): def select_for_phase(st, phase):
''' """
takes a STream object and a phase name and returns that particular component Takes a Stream object and a phase name and returns that particular component
which presumably shows the chosen PHASE best which presumably shows the chosen PHASE best
:param st: stream object containing one or more component[s] :param st: stream object containing one or more component[s]
:type st: `~obspy.core.stream.Stream` :type st: `~obspy.core.stream.Stream`
:param phase: label of the phase for which the stream selection is carried :param phase: label of the phase for which the stream selection is carried out; 'P' or 'S'
out; 'P' or 'S'
:type phase: str :type phase: str
:return: :return: stream object containing the selected phase
''' :rtype: `~obspy.core.stream.Stream`
"""
from pylot.core.util.defaults import SetChannelComponents from pylot.core.util.defaults import SetChannelComponents
sel_st = Stream() sel_st = Stream()
@ -569,21 +573,22 @@ def select_for_phase(st, phase):
def wadaticheck(pickdic, dttolerance, iplot=0, fig_dict=None): def wadaticheck(pickdic, dttolerance, iplot=0, fig_dict=None):
''' """
Function to calculate Wadati-diagram from given P and S onsets in order Function to calculate Wadati-diagram from given P and S onsets in order
to detect S pick outliers. If a certain S-P time deviates by dttolerance to detect S pick outliers. If a certain S-P time deviates by dttolerance
from regression of S-P time the S pick is marked and down graded. from regression of S-P time the S pick is marked and down graded.
:param pickdic: dictionary containing picks and quality parameters
: param: pickdic, dictionary containing picks and quality parameters :type pickdic: dict
: type: dictionary :param dttolerance: dttolerance, maximum adjusted deviation of S-P time from
: param: dttolerance, maximum adjusted deviation of S-P time from
S-P time regression S-P time regression
: type: float :type dttolerance: float
:param iplot: iplot, if iplot > 1, Wadati diagram is shown
: param: iplot, if iplot > 1, Wadati diagram is shown :type iplot: int
: type: int :param fig_dict: Matplotlib figure used for plotting
''' :type fig_dict: `~matplotlib.figure.Figure`
:return: dictionary containing all onsets that passed the wadati check
:rtype: dict
"""
checkedonsets = pickdic checkedonsets = pickdic
@ -714,48 +719,51 @@ def wadaticheck(pickdic, dttolerance, iplot=0, fig_dict=None):
def RMS(X): def RMS(X):
''' """
Function returns root mean square of a given array X Returns root mean square of a given array X
''' :param X: Array
:type X: `~numpy.ndarray`
:return: root mean square value of given array
:rtype: float
"""
return np.sqrt(np.sum(np.power(X, 2)) / len(X)) return np.sqrt(np.sum(np.power(X, 2)) / len(X))
def checksignallength(X, pick, TSNR, minsiglength, nfac, minpercent, iplot=0, fig=None, linecolor='k'): def checksignallength(X, pick, TSNR, minsiglength, nfac, minpercent, iplot=0, fig=None, linecolor='k'):
''' """
Function to detect spuriously picked noise peaks. Function to detect spuriously picked noise peaks.
Uses RMS trace of all 3 components (if available) to determine, Uses RMS trace of all 3 components (if available) to determine,
how many samples [per cent] after P onset are below certain how many samples [per cent] after P onset are below certain
threshold, calculated from noise level times noise factor. threshold, calculated from noise level times noise factor.
:param X: time series (seismogram)
: param: X, time series (seismogram) :type X: `~obspy.core.stream.Stream`
: type: `~obspy.core.stream.Stream` :param pick: initial (AIC) P onset time
:type pick: float
: param: pick, initial (AIC) P onset time :param TSNR: length of time windows around initial pick [s]
: type: float :type TSNR: (T_noise, T_gap, T_signal)
:param minsiglength: minium required signal length [s] to declare pick as P onset
: param: TSNR, length of time windows around initial pick [s] :type minsiglength: float
: type: tuple (T_noise, T_gap, T_signal) :param nfac: noise factor (nfac * noise level = threshold)
:type nfac: float
: param: minsiglength, minium required signal length [s] to :param minpercent: minimum required percentage of samples above calculated threshold
declare pick as P onset :type minpercent: float
: type: float :param iplot: iplot, if iplot > 1, results are shown in figure
:type iplot: int
: param: nfac, noise factor (nfac * noise level = threshold) :param fig: Matplotlib figure to plot results in
: type: float :type fig: `~matplotlib.figure.Figure`
:param linecolor: color of seismic traces
: param: minpercent, minimum required percentage of samples :type linecolor: str
above calculated threshold :return: flag, value of 1 if signal reached required length, 0 if signal is shorter than
: type: float required length
:rtype: int
: param: iplot, if iplot > 1, results are shown in figure """
: type: int
'''
plt_flag = 0 plt_flag = 0
try: try:
iplot = int(iplot) iplot = int(iplot)
except: except:
if iplot == True or iplot == 'True': if real_Bool(iplot):
iplot = 2 iplot = 2
else: else:
iplot = 0 iplot = 0
@ -828,21 +836,26 @@ def checksignallength(X, pick, TSNR, minsiglength, nfac, minpercent, iplot=0, fi
def checkPonsets(pickdic, dttolerance, jackfactor=5, iplot=0, fig_dict=None): def checkPonsets(pickdic, dttolerance, jackfactor=5, iplot=0, fig_dict=None):
''' """
Function to check statistics of P-onset times: Control deviation from Function to check statistics of P-onset times: Control deviation from
median (maximum adjusted deviation = dttolerance) and apply pseudo- median (maximum adjusted deviation = dttolerance) and apply pseudo-
bootstrapping jackknife. bootstrapping jackknife.
:param pickdic: dictionary containing picks and quality parameters
: param: pickdic, dictionary containing picks and quality parameters :type pickdic: dict
: type: dictionary :param dttolerance: maximum adjusted deviation of P onset time from the
: param: dttolerance, maximum adjusted deviation of P-onset time from
median of all P onsets median of all P onsets
: type: float :type dttolerance: float
:param jackfactor: if pseudo value is larger than jackfactor * Jackknife estimator,
: param: iplot, if iplot > 1, Wadati diagram is shown the distorts the estimator too much and will be removed
: type: int :type jackfactor: int
''' :param iplot: if iplot > 1, Wadati diagram is shown
:type iplot: int
:param fig_dict: Matplotlib figure used for plotting
:type fig_dict: `~matplotlib.figure.Figure`
:return: dictionary containing all onsets that passed the jackknife and the
median test
:rtype: dict
"""
checkedonsets = pickdic checkedonsets = pickdic
@ -943,24 +956,27 @@ def checkPonsets(pickdic, dttolerance, jackfactor=5, iplot=0, fig_dict=None):
return checkedonsets return checkedonsets
def jackknife(X, phi, h): def jackknife(X, phi, h=1):
''' """
Function to calculate the Jackknife Estimator for a given quantity, Function to calculate the Jackknife Estimator for a given quantity,
special type of boot strapping. Returns the jackknife estimator PHI_jack special type of boot strapping.
the pseudo values PHI_pseudo and the subgroup parameters PHI_sub.
: param: X, given quantity Returns the jackknife estimator PHI_jack the pseudo values PHI_pseudo
: type: list and the subgroup parameters PHI_sub.
:param X: list containing UTCDateTime objcects representing P onsets
: param: phi, chosen estimator, choose between: :type X: list (`~obspy.core.utcdatetime.UTCDateTime`)
:param phi:phi, chosen estimator, choose between:
"MED" for median "MED" for median
"MEA" for arithmetic mean "MEA" for arithmetic mean
"VAR" for variance "VAR" for variance
: type: string :type phi: str
:param h: size of subgroups, optional (default = 1)
: param: h, size of subgroups, optinal, default = 1 :type h: int
: type: integer :return: Tuple containing the Jackknife estimator PHI_jack, a list of jackknife pseudo
''' values (PHI_pseudo) and the Jackknife estimators (PHI_sub) of the subgroups.
Will return (None, None, None) if X cannot be divided in h subgroups of equals size
:rtype: (float, list, list)
"""
PHI_jack = None PHI_jack = None
PHI_pseudo = None PHI_pseudo = None
@ -1008,40 +1024,42 @@ def jackknife(X, phi, h):
def checkZ4S(X, pick, zfac, checkwin, iplot, fig=None, linecolor='k'): def checkZ4S(X, pick, zfac, checkwin, iplot, fig=None, linecolor='k'):
''' """
Function to compare energy content of vertical trace with Function to compare energy content of vertical trace with
energy content of horizontal traces to detect spuriously energy content of horizontal traces to detect spuriously
picked S onsets instead of P onsets. Usually, P coda shows picked S onsets instead of P onsets.
larger longitudal energy on vertical trace than on horizontal
traces, where the transversal energy is larger within S coda.
Be careful: there are special circumstances, where this is not
the case!
: param: X, fitered(!) time series, three traces Usually, P coda shows larger longitudal energy on vertical trace
: type: `~obspy.core.stream.Stream` than on horizontal traces, where the transversal energy is larger
within S coda. Be careful: there are special circumstances, where
this is not the case!
To pass the test, vertical P-coda level must exceed horizontal P-coda level
zfac times EN-coda level
: param: pick, initial (AIC) P onset time :param X: fitered(!) time series, three traces
: type: float :type X: `~obspy.core.stream.Stream`
:param pick: initial (AIC) P onset time
: param: zfac, factor for threshold determination, :type pick: float
vertical energy must exceed coda level times zfac :param zfac: factor for threshold determination, vertical energy must
to declare a pick as P onset exceed coda level times zfac to declare a pick as P onset
: type: float :type zfac: float
:param checkwin: window length [s] for calculating P-coda engergy content
: param: checkwin, window length [s] for calculating P-coda :type checkwin: float
energy content :param iplot: if iplot > 1, energy content and threshold are shown
: type: float :type iplot: int
:param fig: Matplotlib figure to plot results in
: param: iplot, if iplot > 1, energy content and threshold :type fig: `~matplotlib.figure.Figure`
are shown :param linecolor: color of seismic traces
: type: int :type linecolor: str
''' :return: returnflag; 0 if onset failed test, 1 if onset passed test
:rtype: int
"""
plt_flag = 0 plt_flag = 0
try: try:
iplot = int(iplot) iplot = int(iplot)
except: except:
if iplot == True or iplot == 'True': if real_Bool(iplot):
iplot = 2 iplot = 2
else: else:
iplot = 0 iplot = 0
@ -1154,9 +1172,15 @@ def checkZ4S(X, pick, zfac, checkwin, iplot, fig=None, linecolor='k'):
def getQualityFromUncertainty(uncertainty, Errors): def getQualityFromUncertainty(uncertainty, Errors):
'''Script to transform uncertainty into quality classes 0-4 """
regarding adjusted time errors Errors. Script to transform uncertainty into quality classes 0-4 regarding adjusted time errors
''' :param uncertainty: symmetric picking error of picks
:type uncertainty: float
:param Errors: Width of uncertainty classes 0-4 in seconds
:type Errors: list
:return: quality of pick (0-4)
:rtype: int
"""
# set initial quality to 4 (worst) and change only if one condition is hit # set initial quality to 4 (worst) and change only if one condition is hit
quality = 4 quality = 4