BPMF.similarity_search

class BPMF.similarity_search.MatchedFilter(template_group, min_channels=6, min_stations=3, max_kurto=100.0, remove_edges=True, normalize=True, max_CC_threshold=0.8, n_network_chunks=1, threshold_type='rms', step=-10, max_memory=None, max_workers=None, num_threads_threshold=None, anomalous_cdf_at_mean_plus_1sig=0.0, window_for_validation_Tmax=100.0, offset_win_peak_amp_sec=1.0, duration_win_peak_amp_sec=3.0, phase_on_comp_peak_amp={'E': 'S', 'N': 'S', 'Z': 'P'})[source]

Bases: object

Class for running a matched filter search and detecting earthquakes.

property components

compute_cc_time_series(weight_type='simple', device='cpu', tids=None)[source]

Compute the CC time series (step 1 of matched-filter search).

Parameters:

weight_type (string, default to 'simple') – ‘simple’ is the only option for now.
device (string, default to 'cpu') – Either ‘cpu’ or ‘gpu’.
tids (list of tid, default to None) – If None, run the matched filter search with all templates in self.template_group. If not None, the matched-filter search is run with a limited number of templates (convenient to not overflow the device’s memory).

find_detections(minimum_interevent_time, threshold_window_dur=1800.0, overlap=0.25, sanity_check=True, verbose=0)[source]

Analyze the time series of correlation coefficients to find detections.

Parameters:

minimum_interevent_time (scalar, float) – The shortest duration, in seconds, allowed between two consecutive detections.
threshold_window_dur (scalar float, default to 600) – Duration, in seconds, of the sliding window used in the computation of the time-dependent detection threshold.
sanity_check (boolean, default to True) – If True, check that the kurtosis of the CC time series is not above self.max_kurto. Set to False to speed up the computation.
verbose (scalar int, default to 0) – If > 0, print some messages.

Returns:

detections – Dictionary where detections[tid] is a list of dataset.Event for all events detected with template tid.

Return type:

dictionary,

property memory_cc_time_series

plot_cc(tid, ax=None, detection=None, **kwargs)[source]

Plot the time series of correlation coefficients.

Parameters:

tid (string or scalar int) – The id of the template that produces the CCs.
ax (plt.Axes, default to None) – If not None, plot in this axis.
detection (dataset.Event, default to None) – A dataset.Event instance of a given detection.
figsize (tuple, default to (20, 7)) – Width and height of the figure, in inches.

Returns:

fig – The Figure instance produced by this method.

Return type:

plt.Figure

plot_detection(detection, figsize=(20, 20), component_aliases={'E': ['E', '2'], 'N': ['N', '1'], 'Z': ['Z']}, n_max_stations=None)[source]

Plot a detection and the correlation coefficients.

Parameters:

detection (dataset.Event) – A dataset.Event instance of a given detection.
figsize (tuple, default to (20, 20)) – Widht and height of the figure, in inches.
component_aliases (Dictionary, optional) – Sometimes, components might be named differently than N, E, Z. This dictionary tells the function which alternative component names can be associated with each “canonical” component. For example, component_aliases[‘N’] = [‘N’, ‘1’] means that the function will also check the ‘1’ component in case the ‘N’ component doesn’t exist.

Returns:

fig – The Figure instance produced by this method.

Return type:

plt.Figure

run_matched_filter_search(minimum_interevent_time, weight_type='simple', device='cpu', threshold_window_dur=1800.0, overlap=0.25, sanity_check=True, extract_peak_amplitudes=True, verbose=0, **kwargs)[source]

Run the matched-filter search.

If self.max_memory is specified, divide the task into chunks so that the device memory is not exceeded.

Parameters:

minimum_interevent_time (scalar float) – The shortest duration, in seconds, allowed between two consecutive detections.
weight_type (string, default to 'simple') – Either of ‘simple (default), ‘distance’, or ‘snr’.
device (string, default to 'cpu') – Either ‘cpu’ or ‘gpu’.
threshold_window_dur (scalar float, default to 600) – Duration, in seconds, of the sliding window used in the computation of the time-dependent detection threshold.
sanity_check (boolean, default to True) – If True, check that the kurtosis of the CC time series is not above self.max_kurto. Set to False to speed up the computation.
verbose (scalar int, default to 0) – If > 0, print some messages.

Returns:

detections – Dictionary where detections[tid] is a list of dataset.Event for all events detected with template tid.

Return type:

dictionary,

select_cc_indexes(cc_t, threshold, search_win, anomalous_cdf_at_mean_plus_1sig=0.5, window_for_validation_Tmax=100.0)[source]

Select the peaks in the CC time series.

Parameters:

cc_t ((n_corr,) numpy.ndarray) – The CC time series for one template.
threshold ((n_corr,) numpy.ndarray or scalar) – The detection threshold.
search_win (scalar int) – The minimum inter-event time, in units of correlation step.
anomalous_cdf_at_mean_plus_1sig (scalar float, optional) – Anomalous cumulative distribution function (cdf), between 0 and 1, at {mean + 1xsigma}(CC), default to 0.50. The CC distribution is approximately gaussian and, therefore, the expected value of {mean + 1xsigma}(CC) is 0.78. If {mean + 1xsigma}(CC) is significantly lower than 0.78 in the vicinity of a CC(t) that exceeded threshold, that is, lower than anomalous_cdf_at_mean_plus_1sig, then we consider that {mean + 1xsigma}(CC) was not properly estimated at time t. Since {mean + 1xsigma}(CC) is computed from threshold, the detection threshold was probably not adequate and we discard CC(t). Set this parameter to zero to deactivate validation of the detection threshold.
window_for_validation_Tmax (scalar float, optional) – Window duration, in units of Tmax, the longest period in the data (that is, the inverse of cfg.MIN_FREQ_HZ), for analyzing the statistic of CC(t) in the vicinity of each CC(t) > threshold. Default to 100.

Returns:

cc_idx – The list of all selected CC indexes. They give the timings of the detected events.

Return type:

(n_detections,) numpy.ndarray

set_data(data)[source]

Attribute dataset.Data instance to self.

Parameters:: data (dataset.Data instance) – The dataset.Data instance to read the continuous data to scan.

property stations

BPMF.similarity_search.time_dependent_threshold(time_series, sliding_window, overlap=0.66, threshold_type='rms', white_noise=None, num_threads=None)[source]

Time dependent detection threshold.

Parameters:

time_series ((n_correlations) array_like) – The array of correlation coefficients calculated by FMF (float 32).
sliding_window (scalar integer) – The size of the sliding window, in samples, used to calculate the time dependent central tendency and deviation of the time series.
overlap (scalar float, default to 0.75) –
threshold_type (string, default to 'rms') – Either rms or mad, depending on which measure of deviation you want to use.
white_noise (numpy.ndarray or None, default to None) – If not None, white_noise is a vector of random values sampled from the standard normal distribution. It is used to fill zeros in the CC time series. If None, a random vector is generated from scratch.

Returns:

threshold – Returns the time dependent threshold, with same size as the input time series.

Return type:

(n_correlations) array_like