User classes and functions

The classes and functions presented below are available to the user when importing the kvp package in one their scripts (or packages, feel free build upon it). Please note that array inputs are always assumed to be NumPy arrays even when not explicitly mentioned.

Running the algorithm

class KVP[source]

Main class to run the KVP algorithm. Instances of this class are used to run the algorithm with the stored parameters, as long as the input data is suitable (i.e. sufficient sampling rate and number of samples). The most basic input requires a data array, its sampling rate and an optional POSIX timestamp to be used as reference, i.e. the start time of the data. ObsPy Trace instances can be simply be passed to the obspy() method, which will handle everything.

Inputs are fed through the run() method.

Parameter restrictions

The following restrictions apply when setting the parameters or trying to run the algorithm:

  • Jump window length cannot be longer than CF window length, and typically should be much smaller (e.g. 2 cycles vs 90 cycles).

  • Any input array must be long enough to fit all CF windows, and thus the largest scale, i.e. lowest central frequency, determines the minimum required duration. Users must account for this when cutting their data for inputs, ideally leaving space on both sides.

  • Sampling rates must be at least five times larger than the highest central frequency, otherwise the convolving wavelet would not really be a Ricker.

Parameters:

  • freqmax (float) – Central frequency of the highest scale

  • octaves (int) – Number of octaves

  • voices (int) – Number of voices per octave

  • cf_cycles (float) – Length of CF sliding windows, in cycles

  • jmp_cycles (float) – Length of jump windows, in cycles

  • jump (float) – Kurtosis jump threshold for triggers

  • mingap (float) – Minimum gap between triggers, in seconds

  • nbands (int) – Required number of triggered bands to preserve picks

  • downsample (bool, optional) – Flag to downsample lower scales, default is True

  • N_max (int, optional) – Maximum number of expected possible grouped picks, default is 1000000

obspy(trace, **kwargs)[source]

Run the picking algorithm for an input ObsPy Trace.

Parameters:

  • trace (obspy.Trace) – Input trace

  • kwargs – Keyword arguments, these are passed to run()

run(data, fs, posix_ref=0.0, rec_id='', wt_traces=False, cf_traces=False)[source]

Run the picking algorithm for an input data array.

Parameters:

  • data (numpy.ndarray) – Input data array

  • fs (float) – Sampling rate of input data

  • posix_ref (float, optional) – Reference POSIX timestamp (starting time of data), defaults to 0.0 if not given (1970-01-01T00:00:00)

  • rec_id (str, optional) – Text identifier for the input data, e.g. {network}.{station}.{channel_code}

  • wt_traces (bool, optional) – Flag to include filtered traces on the output, default is False

  • cf_traces (bool, optional) – Flag to include CF traces on the output, default is False

ALLOC_CAPTURE(N_max)[source]

Explicitly allocate memory for the capture algorithm, which avoids continuous reallocation during successive runs if the maximum number of possible picks grows after each run. A large enough pre-allocation will improve performance, if it lasts.

The default value should be enough for any reasonable input data.

Parameters:

N_max (int) – Maximum number of expected possible grouped picks

Utilities

centralfreqs(freqmax, octaves, voices)[source]

Utility function to get the central frequencies for a wavelet family, given the relevant KVP parameters.

Parameters:

  • freqmax (float) – Central frequency of the highest scale

  • octaves (int) – Number of octaves

  • voices (int) – Number of voices per octave