4.6.4.1.1. 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.
Warning
Changing between scipy.linalg.svd solvers (obvious changes between scipy version 0.18.x and 0.19.0) result in sign changes in svd results. You should only run a detector created using the same scipy version as you currently run.
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
([stachans, size, show])Calculate the average percentage energy capture for this subspace. partition
(dimension)Partition subspace into desired dimension. plot
([stachans, size, show])Plot the output basis vectors for the detector at the given 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]¶ Initialize self. See help(type(self)) for accurate signature.
-
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.- streams (list) – List of
-
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: 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
(stachans='all', size=(10, 7), show=False)[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.
-
plot
(stachans='all', size=(10, 7), show=True)[source]¶ Plot the output basis vectors for the detector at the given dimension.
Corresponds to the first n horizontal vectors of the V matrix.
Parameters: - stachans (list) – list of tuples of station, channel pairs to plot.
- stachans – List of tuples of (station, channel) to use. Can set to ‘all’ to use all the station-channel pairs available. If detector is multiplexed, will just plot that.
- size (tuple) – Figure size.
- show (bool) – Whether or not to show the figure.
Returns: Figure
Return type: matplotlib.pyplot.Figure
Note
See
eqcorrscan.utils.plotting.subspace_detector_plot()
for example.