# 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)

  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)
  `construct`(streams, lowcut, highcut, filt_order, sampling_rate, multiplex, name, align, shift_len=0, reject=0.3, no_missed=True, plot=False)

    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)

    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`(stachans='all', size=(10, 7), show=False)

    Calculate the average percentage energy capture for this subspace.

    Returns: | Percentage energy capture
    Return type: | float

  `partition`(dimension)

    Partition subspace into desired dimension.

    Parameters: | dimension (int) Maximum dimension to use.

  `plot`(stachans='all', size=(10, 7), show=True)

    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.

  `read`(filename)

    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)

    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.