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: - 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. -
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 usingeqcorrscan.utils.sfile_util.eventtosfile()
and located externally.Return type: 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)
-
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: 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