# 4.6.3.1.2. match_filter.Family

class `eqcorrscan.core.match_filter.``Family`(template, detections=None, catalog=None)

  Bases: `object`

  Container for Detection objects from a single template.

  Parameters: | template (eqcorrscan.core.match_filter.Template) The template used to detect the family detections (list) list of Detection objects catalog (obspy.core.event.Catalog) Catalog of detections, with information for the individual detections.

  Methods

  `append`(other) | Add another family or detection to the family.
  `copy`() | Returns a copy of the family.
  `lag_calc`(stream, pre_processed[, shift_len, ...]) | Compute picks based on cross-correlation alignment.
  `plot`([plot_grouped]) | Plot the cumulative number of detections in time.
  `sort`() | Sort by detection time.
  `write`(filename[, format]) | Write Family out, select output format.

  `__init__`(template, detections=None, catalog=None)

    Instantiation of Family object.

  `append`(other)

    Add another family or detection to the family.

    Example

    Append a family to a family

        >>> family_a = Family(template=Template(name='a'))
        >>> family_b = Family(template=Template(name='a'))
        >>> family_a.append(family_b)
        Family of 0 detections from template a

    Append a detection to the family

        >>> family_a = Family(template=Template(name='a'))
        >>> detection = Detection(
        ...     template_name='a', detect_time=UTCDateTime(), no_chans=5,
        ...     detect_val=2.5, threshold=1.23, typeofdet='corr',
        ...     threshold_type='MAD', threshold_input=8.0)
        >>> family_a.append(detection)
        Family of 1 detections from template a

  `copy`()

    Returns a copy of the family.

    Returns: | Copy of family

    Example

        >>> family = Family(
        ...     template=Template(name='a'), detections=[
        ...     Detection(template_name='a', detect_time=UTCDateTime(0),
        ...               no_chans=8, detect_val=4.2, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 10,
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0)])
        >>> family == family.copy()
        True

  `lag_calc`(stream, pre_processed, shift_len=0.2, min_cc=0.4, horizontal_chans=['E', 'N', '1', '2'], vertical_chans=['Z'], cores=1, interpolate=False, plot=False, parallel=True, debug=0)

    Compute picks based on cross-correlation alignment.

    Parameters: | stream (obspy.core.stream.Stream) All the data needed to cut from - can be a gappy Stream. pre_processed (bool) Whether the stream has been pre-processed or not to match the templates. See note below. shift_len (float) Shift length allowed for the pick in seconds, will be plus/minus this amount - default=0.2 min_cc (float) Minimum cross-correlation value to be considered a pick, default=0.4. horizontal_chans (list) List of channel endings for horizontal-channels, on which S-picks will be made. vertical_chans (list) List of channel endings for vertical-channels, on which P-picks will be made. cores (int) Number of cores to use in parallel processing, defaults to one. interpolate (bool) Interpolate the correlation function to achieve sub-sample precision. plot (bool) To generate a plot for every detection or not, defaults to False parallel (bool) Turn parallel processing on or off. debug (int) Debug output level, 0-5 with 5 being the most output.
    Returns: | Catalog of events with picks. No origin information is included. These events can then be written out via `obspy.core.event.Catalog.write()`, or to Nordic Sfiles using `eqcorrscan.utils.sfile_util.eventtosfile()` and located externally.
    Return type: | obspy.core.event.Catalog

    Note

    Note on pre-processing: You can provide a pre-processed stream, which may be beneficial for detections over large time periods (the stream can have gaps, which reduces memory usage). However, in this case the processing steps are not checked, so you must ensure that all the template in the Party have the same sampling rate and filtering as the stream. If pre-processing has not be done then the data will be processed according to the parameters in the templates, in this case templates will be grouped by processing parameters and run with similarly processed data. In this case, all templates do not have to have the same processing parameters.

    Note

    Picks are corrected for the template pre-pick time.

  `plot`(plot_grouped=False)

    Plot the cumulative number of detections in time.

    Example

        >>> family = Family(
        ...     template=Template(name='a'), detections=[
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 200,
        ...               no_chans=8, detect_val=4.2, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0),
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 10,
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0)])
        >>> family.plot(plot_grouped=True)

    (Source code, png, hires.png)

  `sort`()

    Sort by detection time.

    Example

        >>> family = Family(
        ...     template=Template(name='a'), detections=[
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 200,
        ...               no_chans=8, detect_val=4.2, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0),
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 10,
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0)])
        >>> family[0].detect_time
        UTCDateTime(1970, 1, 1, 0, 3, 20)
        >>> family.sort()[0].detect_time
        UTCDateTime(1970, 1, 1, 0, 0)

  `write`(filename, format='tar')

    Write Family out, select output format.

    Parameters: | format (str) One of either ‘tar’, ‘csv’, or any obspy supported catalog output. filename (str) Path to write file to.

    Note

    csv format will write out detection objects, all other outputs will write the catalog. These cannot be rebuilt into a Family object. The only format that can be read back into Family objects is the ‘tar’ type.

    Note

    csv format will append detections to filename, all others will overwrite any existing files.

    Example

        >>> family = Family(
        ...     template=Template(name='a', st=read()), detections=[
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 200,
        ...               no_chans=8, detect_val=4.2, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0),
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0),
        ...     Detection(template_name='a', detect_time=UTCDateTime(0) + 10,
        ...               no_chans=8, detect_val=4.5, threshold=1.2,
        ...               typeofdet='corr', threshold_type='MAD',
        ...               threshold_input=8.0)])
        >>> family.write('test_family')
        Writing family 0