# 4.6.3.1.5. match_filter.Tribe

class `eqcorrscan.core.match_filter.``Tribe`(templates=None)

  Bases: `object`

  Holder for multiple templates.

  Methods

  `client_detect`(client, starttime, endtime, ...) | Detect using a Tribe of templates within a continuous stream.
  `cluster`(method, \*\*kwargs) | Cluster the tribe, returns multiple tribes each of which could be stacked.
  `construct`(method, lowcut, highcut, ...) | Generate a Tribe of Templates.
  `copy`() | Copy the Tribe.
  `detect`(stream, threshold, threshold_type, ...) | Detect using a Tribe of templates within a continuous stream.
  `read`(filename) | Read a tribe of templates from a tar formatted file.
  `remove`(template) | Remove a template from the tribe.
  `sort`() | Sort the tribe, sorts by template name.
  `write`(filename[, compress]) | Write the tribe to a file using tar archive formatting.

  `__init__`(templates=None)
  `client_detect`(client, starttime, endtime, threshold, threshold_type, trig_int, plotvar, daylong=False, parallel_process=True, xcorr_func=None, concurrency=None, cores=None, ignore_length=False, group_size=None, debug=0, return_stream=False)

    Detect using a Tribe of templates within a continuous stream.

    Parameters: | client (obspy.clients.*.Client) Any obspy client with a dataselect service. starttime (`obspy.core.UTCDateTime`) Start-time for detections. endtime (`obspy.core.UTCDateTime`) End-time for detections threshold (float) Threshold level, if using threshold_type=’MAD’ then this will be the multiple of the median absolute deviation. threshold_type (str) The type of threshold to be used, can be MAD, absolute or av_chan_corr. See Note on thresholding below. trig_int (float) Minimum gap between detections in seconds. If multiple detections occur within trig_int of one-another, the one with the highest cross-correlation sum will be selected. plotvar (bool) Turn plotting on or off, see warning about plotting below daylong (bool) Set to True to use the `eqcorrscan.utils.pre_processing.dayproc()` routine, which preforms additional checks and is more efficient for day-long data over other methods. parallel_process (bool) xcorr_func (str or callable) A str of a registered xcorr function or a callable for implementing a custom xcorr function. For more information see: `eqcorrscan.utils.correlate.register_array_xcorr()` concurrency (str) The type of concurrency to apply to the xcorr function. Options are ‘multithread’, ‘multiprocess’, ‘concurrent’. For more details see `eqcorrscan.utils.correlate.get_stream_xcorr()` cores (int) Number of workers for processing and detection. ignore_length (bool) If using daylong=True, then dayproc will try check that the data are there for at least 80% of the day, if you don’t want this check (which will raise an error if too much data are missing) then set ignore_length=True. This is not recommended! group_size (int) Maximum number of templates to run at once, use to reduce memory consumption, if unset will use all templates. debug (int) Debug level from 0-5 where five is more output, for debug levels 4 and 5, detections will not be computed in parallel. return_stream (bool) Whether to also output the stream downloaded, useful if you plan to use the stream for something else, e.g. lag_calc.
    Returns: | `eqcorrscan.core.match_filter.Party` of Families of detections.

    Warning

    Picks included in the output Party.get_catalog() will not be corrected for pre-picks in the template.

    Note

    Ensures that data overlap between loops, which will lead to no missed detections at data start-stop points (see note for `eqcorrscan.core.match_filter.Tribe.detect()` method). This will result in end-time not being strictly honoured, so detections may occur after the end-time set. This is because data must be run in the correct process-length.

    Warning

    Plotting within the match-filter routine uses the Agg backend with interactive plotting turned off. This is because the function is designed to work in bulk. If you wish to turn interactive plotting on you must import matplotlib in your script first, when you then import match_filter you will get the warning that this call to matplotlib has no effect, which will mean that match_filter has not changed the plotting behaviour.

    Note

    Thresholding:

    MAD threshold is calculated as the:

    \[threshold {\times} (median(abs(cccsum)))\]

    where \(cccsum\) is the cross-correlation sum for a given template.

    absolute threshold is a true absolute threshold based on the cccsum value.

    av_chan_corr is based on the mean values of single-channel cross-correlations assuming all data are present as required for the template, e.g:

    \[av\_chan\_corr\_thresh=threshold \times (cccsum / len(template))\]

    where \(template\) is a single template from the input and the length is the number of channels within this template.

  `cluster`(method, **kwargs)

    Cluster the tribe, returns multiple tribes each of which could be stacked.

    Parameters: | method (str) Method of stacking, see `eqcorrscan.utils.clustering`
    Returns: | List of tribes.

    Example

  `construct`(method, lowcut, highcut, samp_rate, filt_order, prepick, **kwargs)

    Generate a Tribe of Templates. See `eqcorrscan.core.template_gen` for available methods.

    Parameters: | method Method of Tribe generation. kwargs Arguments for the given method. lowcut (float) Low cut (Hz), if set to None will not apply a lowcut highcut (float) High cut (Hz), if set to None will not apply a highcut. samp_rate (float) New sampling rate in Hz. filt_order (int) Filter level (number of corners). prepick (float) Pre-pick time in seconds

    Note

    Methods: from_contbase, from_sfile and from_sac are not supported by Tribe.construct and must use Template.construct.

    Note

    The Method multi_template_gen is not supported because the processing parameters for the stream are not known. Use from_meta_file instead.

    Note

    Templates will be named according to their start-time.

  `copy`()

    Copy the Tribe.

    Example

        >>> tribe_a = Tribe(templates=[Template(name='a')])
        >>> tribe_b = tribe_a.copy()
        >>> tribe_a == tribe_b
        True

  `detect`(stream, threshold, threshold_type, trig_int, plotvar, daylong=False, parallel_process=True, xcorr_func=None, concurrency=None, cores=None, ignore_length=False, group_size=None, overlap='calculate', debug=0)

    Detect using a Tribe of templates within a continuous stream.

    Parameters: | stream (obspy.core.stream.Stream) Continuous data to detect within using the Template. threshold (float) Threshold level, if using threshold_type=’MAD’ then this will be the multiple of the median absolute deviation. threshold_type (str) The type of threshold to be used, can be MAD, absolute or av_chan_corr. See Note on thresholding below. trig_int (float) Minimum gap between detections in seconds. If multiple detections occur within trig_int of one-another, the one with the highest cross-correlation sum will be selected. plotvar (bool) Turn plotting on or off, see warning about plotting below daylong (bool) Set to True to use the `eqcorrscan.utils.pre_processing.dayproc()` routine, which preforms additional checks and is more efficient for day-long data over other methods. parallel_process (bool) xcorr_func (str or callable) A str of a registered xcorr function or a callable for implementing a custom xcorr function. For more information see: `eqcorrscan.utils.correlate.register_array_xcorr()` concurrency (str) The type of concurrency to apply to the xcorr function. Options are ‘multithread’, ‘multiprocess’, ‘concurrent’. For more details see `eqcorrscan.utils.correlate.get_stream_xcorr()` cores (int) Number of workers for procesisng and detection. ignore_length (bool) If using daylong=True, then dayproc will try check that the data are there for at least 80% of the day, if you don’t want this check (which will raise an error if too much data are missing) then set ignore_length=True. This is not recommended! group_size (int) Maximum number of templates to run at once, use to reduce memory consumption, if unset will use all templates. overlap (float) Either None, “calculate” or a float of number of seconds to overlap detection streams by. This is to counter the effects of the delay-and-stack in calcualting cross-correlation sums. Setting overlap = “calculate” will work out the appropriate overlap based on the maximum lags within templates. debug (int) Debug level from 0-5 where five is more output, for debug levels 4 and 5, detections will not be computed in parallel.
    Returns: | `eqcorrscan.core.match_filter.Party` of Families of detections.

    Note

    stream must not be pre-processed.

    Warning

    Picks included in the output Party.get_catalog() will not be corrected for pre-picks in the template.

    Warning

    Plotting within the match-filter routine uses the Agg backend with interactive plotting turned off. This is because the function is designed to work in bulk. If you wish to turn interactive plotting on you must import matplotlib in your script first, when you then import match_filter you will get the warning that this call to matplotlib has no effect, which will mean that match_filter has not changed the plotting behaviour.

    Note

    Data overlap:

    Internally this routine shifts and trims the data according to the offsets in the template (e.g. if trace 2 starts 2 seconds after trace 1 in the template then the continuous data will be shifted by 2 seconds to align peak correlations prior to summing). Because of this, detections at the start and end of continuous data streams may be missed. The maximum time-period that might be missing detections is the maximum offset in the template.

    To work around this, if you are conducting matched-filter detections through long-duration continuous data, we suggest using some overlap (a few seconds, on the order of the maximum offset in the templates) in the continuous data. You will then need to post-process the detections (which should be done anyway to remove duplicates). See below note for how overlap argument affects data internally if stream is longer than the processing length.

    Note

    If stream is long then processing length, this routine will ensure that data overlap between loops, which will lead to no missed detections at data start-stop points (see above note). This will result in end-time not being strictly honoured, so detections may occur after the end-time set. This is because data must be run in the correct process-length.

    Note

    Thresholding:

    MAD threshold is calculated as the:

    \[threshold {\times} (median(abs(cccsum)))\]

    where \(cccsum\) is the cross-correlation sum for a given template.

    absolute threshold is a true absolute threshold based on the cccsum value.

    av_chan_corr is based on the mean values of single-channel cross-correlations assuming all data are present as required for the template, e.g:

    \[av\_chan\_corr\_thresh=threshold \times (cccsum / len(template))\]

    where \(template\) is a single template from the input and the length is the number of channels within this template.

  `read`(filename)

    Read a tribe of templates from a tar formatted file.

    Parameters: | filename (str) File to read templates from.

    Example

        >>> tribe = Tribe(templates=[Template(name='c', st=read())])
        >>> tribe.write('test_tribe')
        Tribe of 1 templates
        >>> tribe_back = Tribe().read('test_tribe.tgz')
        >>> tribe_back == tribe
        True

  `remove`(template)

    Remove a template from the tribe.

    Parameters: | template (`eqcorrscan.core.match_filter.Template`) Template to remove from tribe

    Example

        >>> tribe = Tribe(templates=[Template(name='c'), Template(name='b'),
        ...                          Template(name='a')])
        >>> tribe.remove(tribe.templates[0])
        Tribe of 2 templates

  `sort`()

    Sort the tribe, sorts by template name.

    Example

        >>> tribe = Tribe(templates=[Template(name='c'), Template(name='b'),
        ...                          Template(name='a')])
        >>> tribe.sort()
        Tribe of 3 templates
        >>> tribe[0]
        Template a:
         0 channels;
         lowcut: None Hz;
         highcut: None Hz;
         sampling rate None Hz;
         filter order: None;
         process length: None s

  `write`(filename, compress=True)

    Write the tribe to a file using tar archive formatting.

    Parameters: | filename (str) Filename to write to, if it exists it will be appended to. compress (bool) Whether to compress the tar archive or not, if False then will just be files in a folder.

    Example

        >>> tribe = Tribe(templates=[Template(name='c', st=read())])
        >>> tribe.write('test_tribe')
        Tribe of 1 templates