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

[change] docstrings for functions in charfuns.py

Browse Source
This commit is contained in:
Darius Arnold 2017-10-05 16:50:53 +02:00
parent 5931331b1d
commit 9a8d7da0e6
1 changed files with 86 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
pylot/core/pick/charfuns.py
View File

@ -22,33 +22,27 @@ from obspy.core import Stream
class CharacteristicFunction(object): class CharacteristicFunction(object):
''' """
SuperClass for different types of characteristic functions. SuperClass for different types of characteristic functions.
''' """
def __init__(self, data, cut, t2=None, order=None, t1=None, fnoise=None): def __init__(self, data, cut, t2=None, order=None, t1=None, fnoise=None):
''' """
Initialize data type object with information from the original Initialize data type object with information from the original
Seismogram. Seismogram.
:param data: stream object containing traces for which the cf should
:param: data be calculated
:type: `~obspy.core.stream.Stream` :type data: ~obspy.core.stream.Stream
:param cut: (starttime, endtime) in seconds relative to beginning of trace
:param: cut :type cut: tuple
:type: tuple :param t2:
:type t2: float
:param: t2 :param order:
:type: float :type order: int
:param t1: float (optional, only for AR)
:param: order :param fnoise: (optional, only for AR)
:type: int :type fnoise: float
"""
:param: t1
:type: float (optional, only for AR)
:param: fnoise
:type: float (optional, only for AR)
'''
assert isinstance(data, Stream), "%s is not a stream object" % str(data) assert isinstance(data, Stream), "%s is not a stream object" % str(data)
@ -120,6 +114,10 @@ class CharacteristicFunction(object):
return self.dt return self.dt
def getTimeArray(self): def getTimeArray(self):
"""
:return: array if time indices
:rtype: np.array
"""
incr = self.getIncrement() incr = self.getIncrement()
self.TimeArray = np.arange(0, len(self.getCF()) * incr, incr) + self.getCut()[0] self.TimeArray = np.arange(0, len(self.getCF()) * incr, incr) + self.getCut()[0]
return self.TimeArray return self.TimeArray
@ -137,13 +135,15 @@ class CharacteristicFunction(object):
return self.xcf return self.xcf
def getDataArray(self, cut=None): def getDataArray(self, cut=None):
''' """
If cut times are given, time series is cut from cut[0] (start time) If cut times are given, time series is cut from cut[0] (start time)
till cut[1] (stop time) in order to calculate CF for certain part till cut[1] (stop time) in order to calculate CF for certain part
only where you expect the signal! only where you expect the signal!
input: cut (tuple) () :param cut: contains (start time, stop time) for cutting the time series
cutting window :type cut: tuple
''' :return: cut data/time series
:rtype:
"""
if cut is not None: if cut is not None:
if len(self.orig_data) == 1: if len(self.orig_data) == 1:
if self.cut[0] == 0 and self.cut[1] == 0: if self.cut[0] == 0 and self.cut[1] == 0:
@ -209,17 +209,15 @@ class CharacteristicFunction(object):
class AICcf(CharacteristicFunction): class AICcf(CharacteristicFunction):
'''
Function to calculate the Akaike Information Criterion (AIC) after
Maeda (1985).
:param: data, time series (whether seismogram or CF)
:type: tuple
Output: AIC function
'''
def calcCF(self, data): def calcCF(self, data):
"""
Function to calculate the Akaike Information Criterion (AIC) after Maeda (1985).
:param data: data, time series (whether seismogram or CF)
:type data: tuple
:return: AIC function
:rtype:
"""
x = self.getDataArray() x = self.getDataArray()
xnp = x[0].data xnp = x[0].data
ind = np.where(~np.isnan(xnp))[0] ind = np.where(~np.isnan(xnp))[0]
@ -244,14 +242,17 @@ class AICcf(CharacteristicFunction):
class HOScf(CharacteristicFunction): class HOScf(CharacteristicFunction):
'''
Function to calculate skewness (statistics of order 3) or kurtosis
(statistics of order 4), using one long moving window, as published
in Kueperkoch et al. (2010).
'''
def calcCF(self, data): def calcCF(self, data):
"""
Function to calculate skewness (statistics of order 3) or kurtosis
(statistics of order 4), using one long moving window, as published
in Kueperkoch et al. (2010).
:param data: data, time series (whether seismogram or CF)
:type data: tuple
:return: HOS cf
:rtype:
"""
x = self.getDataArray(self.getCut()) x = self.getDataArray(self.getCut())
xnp = x[0].data xnp = x[0].data
nn = np.isnan(xnp) nn = np.isnan(xnp)
@ -297,8 +298,16 @@ class HOScf(CharacteristicFunction):
class ARZcf(CharacteristicFunction): class ARZcf(CharacteristicFunction):
def calcCF(self, data):
def calcCF(self, data):
"""
function used to calculate the AR prediction error from a single vertical trace. Can be used to pick
P onsets.
:param data:
:type data: ~obspy.core.stream.Stream
:return: ARZ cf
:rtype:
"""
print('Calculating AR-prediction error from single trace ...') print('Calculating AR-prediction error from single trace ...')
x = self.getDataArray(self.getCut()) x = self.getDataArray(self.getCut())
xnp = x[0].data xnp = x[0].data
@ -342,7 +351,7 @@ class ARZcf(CharacteristicFunction):
self.xcf = x self.xcf = x
def arDetZ(self, data, order, rind, ldet): def arDetZ(self, data, order, rind, ldet):
''' """
Function to calculate AR parameters arpara after Thomas Meier (CAU), published Function to calculate AR parameters arpara after Thomas Meier (CAU), published
in Kueperkoch et al. (2012). This function solves SLE using the Moore- in Kueperkoch et al. (2012). This function solves SLE using the Moore-
Penrose inverse, i.e. the least-squares approach. Penrose inverse, i.e. the least-squares approach.
@ -359,7 +368,7 @@ class ARZcf(CharacteristicFunction):
:type: int :type: int
Output: AR parameters arpara Output: AR parameters arpara
''' """
# recursive calculation of data vector (right part of eq. 6.5 in Kueperkoch et al. (2012) # recursive calculation of data vector (right part of eq. 6.5 in Kueperkoch et al. (2012)
rhs = np.zeros(self.getOrder()) rhs = np.zeros(self.getOrder())
@ -383,7 +392,7 @@ class ARZcf(CharacteristicFunction):
self.arpara = np.dot(np.linalg.pinv(A), rhs) self.arpara = np.dot(np.linalg.pinv(A), rhs)
def arPredZ(self, data, arpara, rind, lpred): def arPredZ(self, data, arpara, rind, lpred):
''' """
Function to predict waveform, assuming an autoregressive process of order Function to predict waveform, assuming an autoregressive process of order
p (=size(arpara)), with AR parameters arpara calculated in arDet. After p (=size(arpara)), with AR parameters arpara calculated in arDet. After
Thomas Meier (CAU), published in Kueperkoch et al. (2012). Thomas Meier (CAU), published in Kueperkoch et al. (2012).
@ -400,8 +409,8 @@ class ARZcf(CharacteristicFunction):
:type: int :type: int
Output: predicted waveform z Output: predicted waveform z
''' """
# be sure of the summation indeces # be sure of the summation indices
if rind < len(arpara): if rind < len(arpara):
rind = len(arpara) rind = len(arpara)
if rind > len(data) - lpred: if rind > len(data) - lpred:
@ -421,7 +430,18 @@ class ARZcf(CharacteristicFunction):
class ARHcf(CharacteristicFunction): class ARHcf(CharacteristicFunction):
def calcCF(self, data): def calcCF(self, data):
"""
Function to calculate a characteristic function using autoregressive modelling of the waveform of
both horizontal traces.
The waveform is predicted in a moving time window using the calculated AR parameters. The difference
between the predicted and the actual waveform servers as a characteristic function.
:param data: wavefor stream
:type data: ~obspy.core.stream.Stream
:return: ARH cf
:rtype:
"""
print('Calculating AR-prediction error from both horizontal traces ...') print('Calculating AR-prediction error from both horizontal traces ...')
@ -475,7 +495,7 @@ class ARHcf(CharacteristicFunction):
self.xcf = xnp self.xcf = xnp
def arDetH(self, data, order, rind, ldet): def arDetH(self, data, order, rind, ldet):
''' """
Function to calculate AR parameters arpara after Thomas Meier (CAU), published Function to calculate AR parameters arpara after Thomas Meier (CAU), published
in Kueperkoch et al. (2012). This function solves SLE using the Moore- in Kueperkoch et al. (2012). This function solves SLE using the Moore-
Penrose inverse, i.e. the least-squares approach. "data" is a structured array. Penrose inverse, i.e. the least-squares approach. "data" is a structured array.
@ -494,7 +514,7 @@ class ARHcf(CharacteristicFunction):
:type: int :type: int
Output: AR parameters arpara Output: AR parameters arpara
''' """
# recursive calculation of data vector (right part of eq. 6.5 in Kueperkoch et al. (2012) # recursive calculation of data vector (right part of eq. 6.5 in Kueperkoch et al. (2012)
rhs = np.zeros(self.getOrder()) rhs = np.zeros(self.getOrder())
@ -517,7 +537,7 @@ class ARHcf(CharacteristicFunction):
self.arpara = np.dot(np.linalg.pinv(A), rhs) self.arpara = np.dot(np.linalg.pinv(A), rhs)
def arPredH(self, data, arpara, rind, lpred): def arPredH(self, data, arpara, rind, lpred):
''' """
Function to predict waveform, assuming an autoregressive process of order Function to predict waveform, assuming an autoregressive process of order
p (=size(arpara)), with AR parameters arpara calculated in arDet. After p (=size(arpara)), with AR parameters arpara calculated in arDet. After
Thomas Meier (CAU), published in Kueperkoch et al. (2012). Thomas Meier (CAU), published in Kueperkoch et al. (2012).
@ -535,7 +555,7 @@ class ARHcf(CharacteristicFunction):
Output: predicted waveform z Output: predicted waveform z
:type: structured array :type: structured array
''' """
# be sure of the summation indeces # be sure of the summation indeces
if rind < len(arpara) + 1: if rind < len(arpara) + 1:
rind = len(arpara) + 1 rind = len(arpara) + 1
@ -559,8 +579,18 @@ class ARHcf(CharacteristicFunction):
class AR3Ccf(CharacteristicFunction): class AR3Ccf(CharacteristicFunction):
def calcCF(self, data):
def calcCF(self, data):
"""
Function to calculate a characteristic function using autoregressive modelling of the waveform of
all three traces.
The waveform is predicted in a moving time window using the calculated AR parameters. The difference
between the predicted and the actual waveform servers as a characteristic function
:param data: stream holding all three traces
:type data: ~obspy.core.stream.Stream
:return: AR3C cf
:rtype:
"""
print('Calculating AR-prediction error from all 3 components ...') print('Calculating AR-prediction error from all 3 components ...')
xnp = self.getDataArray(self.getCut()) xnp = self.getDataArray(self.getCut())
@ -618,7 +648,7 @@ class AR3Ccf(CharacteristicFunction):
self.xcf = xnp self.xcf = xnp
def arDet3C(self, data, order, rind, ldet): def arDet3C(self, data, order, rind, ldet):
''' """
Function to calculate AR parameters arpara after Thomas Meier (CAU), published Function to calculate AR parameters arpara after Thomas Meier (CAU), published
in Kueperkoch et al. (2012). This function solves SLE using the Moore- in Kueperkoch et al. (2012). This function solves SLE using the Moore-
Penrose inverse, i.e. the least-squares approach. "data" is a structured array. Penrose inverse, i.e. the least-squares approach. "data" is a structured array.
@ -637,7 +667,7 @@ class AR3Ccf(CharacteristicFunction):
:type: int :type: int
Output: AR parameters arpara Output: AR parameters arpara
''' """
# recursive calculation of data vector (right part of eq. 6.5 in Kueperkoch et al. (2012) # recursive calculation of data vector (right part of eq. 6.5 in Kueperkoch et al. (2012)
rhs = np.zeros(self.getOrder()) rhs = np.zeros(self.getOrder())
@ -662,7 +692,7 @@ class AR3Ccf(CharacteristicFunction):
self.arpara = np.dot(np.linalg.pinv(A), rhs) self.arpara = np.dot(np.linalg.pinv(A), rhs)
def arPred3C(self, data, arpara, rind, lpred): def arPred3C(self, data, arpara, rind, lpred):
''' """
Function to predict waveform, assuming an autoregressive process of order Function to predict waveform, assuming an autoregressive process of order
p (=size(arpara)), with AR parameters arpara calculated in arDet3C. After p (=size(arpara)), with AR parameters arpara calculated in arDet3C. After
Thomas Meier (CAU), published in Kueperkoch et al. (2012). Thomas Meier (CAU), published in Kueperkoch et al. (2012).
@ -680,7 +710,7 @@ class AR3Ccf(CharacteristicFunction):
Output: predicted waveform z Output: predicted waveform z
:type: structured array :type: structured array
''' """
# be sure of the summation indeces # be sure of the summation indeces
if rind < len(arpara) + 1: if rind < len(arpara) + 1:
rind = len(arpara) + 1 rind = len(arpara) + 1