4.6.3.1.2. match_filter.Family

class eqcorrscan.core.match_filter.Family(template, detections=None, catalog=None)[source]

Bases: object

Container for Detection objects from a single template.

Parameters:

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)[source]

Instantiation of Family object.

append(other)[source]

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()[source]

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)[source]

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)[source]

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)

../_images/core-match_filter-Family-1.png
sort()[source]

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’)[source]

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