eqcorrscan.core.subspace.Detector

class eqcorrscan.core.subspace.Detector(name=None, sampling_rate=None, multiplex=None, stachans=None, lowcut=None, highcut=None, filt_order=None, data=None, u=None, sigma=None, v=None, dimension=None)[source]

Bases: object

Class to serve as the base for subspace detections.

Parameters:
  • name (str) Name of subspace detector, used for book-keeping
  • sampling_rate (float) Sampling rate in Hz of original waveforms
  • multiplex (bool) Is this detector multiplexed.
  • stachans (list) List of tuples of (station, channel) used in detector. If multiplexed, these must be in the order that multiplexing was done.
  • lowcut (float) Lowcut filter in Hz
  • highcut (float) Highcut filter in Hz
  • filt_order (int) Number of corners for filtering
  • data (numpy.ndarray) The actual detector
  • u (numpy.ndarray) Full rank U matrix of left (input) singular vectors.
  • sigma (numpy.ndarray) Full rank vector of singular values.
  • v (numpy.ndarray) Full rank right (output) singular vectors.
  • dimension (int) Dimension of data.

Methods

construct(streams, lowcut, highcut, ...[, ...]) Construct a subspace detector from a list of streams, full rank.
detect(st, threshold, trig_int[, moveout, ...]) Detect within continuous data using the subspace method.
energy_capture() Calculate the average percentage energy capture for this subspace.
partition(dimension) Partition subspace into desired dimension.
read(filename) Read detector from a file, must be HDF5 format.
write(filename) Write detector to a file - uses HDF5 file format.
__init__(name=None, sampling_rate=None, multiplex=None, stachans=None, lowcut=None, highcut=None, filt_order=None, data=None, u=None, sigma=None, v=None, dimension=None)[source]
construct(streams, lowcut, highcut, filt_order, sampling_rate, multiplex, name, align, shift_len=0, reject=0.3, no_missed=True, plot=False)[source]

Construct a subspace detector from a list of streams, full rank.

Subspace detector will be full-rank, further functions can be used to select the desired dimensions.

Parameters:
  • streams (list) List of obspy.core.stream.Stream to be used to generate the subspace detector. These should be pre-clustered and aligned.
  • lowcut (float) Lowcut in Hz, can be None to not apply filter
  • highcut (float) Highcut in Hz, can be None to not apply filter
  • filt_order (int) Number of corners for filter.
  • sampling_rate (float) Desired sampling rate in Hz
  • multiplex (bool) Whether to multiplex the data or not. Data are multiplexed according to the method of Harris, see the multi function for details.
  • name (str) Name of the detector, used for book-keeping.
  • align (bool) Whether to align the data or not - needs to be done at some point
  • shift_len (float) Maximum shift allowed for alignment in seconds.
  • reject (float) Minimum correlation to include traces - only used if align=True.
  • no_missed (bool) Reject streams with missed traces, defaults to True. A missing trace from lots of events will reduce the quality of the subspace detector if multiplexed. Only used when multi is set to True.
  • plot (bool) Whether to plot the alignment stage or not.

Note

The detector will be normalized such that the data, before computing the singular-value decomposition, will have unit energy. e.g. We divide the amplitudes of the data by the L1 norm of the data.

Warning

EQcorrscan’s alignment will attempt to align over the whole data window given. For long (more than 2s) chunks of data this can give poor results and you might be better off using the eqcorrscan.utils.stacking.align_traces() function externally, focusing on a smaller window of data. To do this you would align the data prior to running construct.

detect(st, threshold, trig_int, moveout=0, min_trig=0, process=True, extract_detections=False, debug=0)[source]

Detect within continuous data using the subspace method.

Parameters:
  • st (obspy.core.stream.Stream) Un-processed stream to detect within using the subspace detector.
  • threshold (float) Threshold value for detections between 0-1
  • trig_int (float) Minimum trigger interval in seconds.
  • moveout (float) Maximum allowable moveout window for non-multiplexed, network detection. See note.
  • min_trig (int) Minimum number of stations exceeding threshold for non-multiplexed, network detection. See note.
  • process (bool) Whether or not to process the stream according to the parameters defined by the detector. Default is True, which will process the data.
  • extract_detections (bool) Whether to extract waveforms for each detection or not, if True will return detections and streams.
  • debug (int) Debug output level from 0-5.
Returns:

list of eqcorrscan.core.match_filter.DETECTION

Return type:

list

Warning

Subspace is currently in beta, see note in the subspace tutorial for information.

Note

If running in bulk with detectors that all have the same parameters then you can pre-process the data and set process to False. This will speed up this detect function dramatically.

Warning

If the detector and stream are multiplexed then they must contain the same channels and multiplexed in the same order. This is handled internally when process=True, but if running in bulk you must take care.

Note

Non-multiplexed, network detection. When the detector is not multiplexed, but there are multiple channels within the detector, we do not stack the single-channel detection statistics because we do not have a one-size-fits-all solution for computing delays for a subspace detector (if you want to implement one, then please contribute it!). Therefore, these parameters provide a means for declaring a network coincidence trigger using single-channel detection statistics, in a similar fashion to the commonly used network-coincidence trigger with energy detection statistics.

energy_capture()[source]

Calculate the average percentage energy capture for this subspace.

Returns:Percentage energy capture
Return type:float
partition(dimension)[source]

Partition subspace into desired dimension.

Parameters:dimension (int) Maximum dimension to use.
read(filename)[source]

Read detector from a file, must be HDF5 format.

Reads a Detector object from an HDF5 file, usually created by eqcorrscan.

Parameters:filename (str) Filename to save the detector to.
write(filename)[source]

Write detector to a file - uses HDF5 file format.

Meta-data are stored alongside numpy data arrays. See h5py.org for details of the methods.

Parameters:filename (str) Filename to save the detector to.