API

Python bindings for the fast_matched_filter C libraries

copyright:

William B. Frank and Eric Beauce

license:

GNU General Public License, Version 3 (https://www.gnu.org/licenses/gpl-3.0.en.html)

fast_matched_filter.fast_matched_filter.matched_filter(templates, moveouts, weights, data, step, n_samples_template=None, arch='cpu', check_zeros='first', normalize='short', network_sum=True)[source]

Compute the correlation coefficients between templates and data.

Scan the continuous waveforms data with the template waveforms templates given the relative propagation times moveouts and compute a time series of summed correlation coefficients. The weighted sum is defined by weights. Try normalize=’full’ and/or arch=’precise’ or ‘gpu’ to achieve better numerical precision.

Parameters:

  • templates (numpy.ndarray) – 4D (n_templates, n_stations, n_channels, n_tp_samples) or 3D (n_templates, n_traces, n_tp_samples) numpy.ndarray with the template waveforms.

  • moveouts (numpy.ndarray, int) – 3D (n_templates, n_stations, n_channels) or 2D (n_templates, n_stations) numpy.ndarray with the moveouts, in samples.

  • weights (numpy.ndarray, float) – 3D (n_templates, n_stations, n_channels) or 2D (n_stations, n_channels) numpy.ndarray with the channel weights. For a given template, the largest possible correlation coefficient is given by the sum of the weights. Make sure that the weights sum to one if you want CCs between 1 and -1.

  • data (numpy.ndarray) – 3D (n_stations, n_channels, n_samples) or 2D (n_traces, n_samples) numpy.ndarray with the continuous waveforms.

  • step (scalar, int) – Time interval, in samples, between consecutive correlations.

  • n_samples_template (numpy.ndarray or None, optional) – If not None, it must be a numpy.ndarray with same shape as moveouts. Each element is the length, in samples, of the template waveform at a given channel. Note that, for now, if n_samples_template is not None, the arch key-word argument must be “variable_precise”. Defaults to None.

  • arch (string, optional) –

    One of “cpu”, “precise”, “variable_precise” or “gpu”.

    • ”cpu”: CPU implementation with optimized algorithm to compute the denominator in the correlation coefficient.

    • ”precise”: CPU implementation with non optimized but more accurate algorithm to compute the denominator in the correlation coefficient. This option might be useful when dealing with very large amplitude waveforms.

    • ”variable_precise”: CPU implementation similar to “precise” but also allows to use variable template lengths at every channel.

    • ”gpu”: GPU implementation.

  • check_zeros (string, optional) –

    Controls the verbosity level at the end of this routine when checking zeros in the time series of correlation coefficients (CCs).

    • False: No messages.

    • ’first’: Check zeros on the first template’s CCs (recommended).

    • ’all’: Check zeros on each template’s CCs. It can be useful for

    troubleshooting but in general this would print too many messages. Default is ‘first’.

  • normalize (string, optional) –

    Either “short” or “full”.

    • ”full”: Slow but removes the mean of the data at every correlation.

    • ”short”: This is the original implementation. When using normalize=”short”,

    the templates and the data sliding windows must have zero means (high-pass filter the data if necessary).

  • network_sum (boolean, optional) – If True, returns the weighted sum of correlation coefficients across the station network. If False, returns the correlation coefficients for each channel. Defaults to True.

Returns:

cc – If network_sum=True, 2D (n_templates, n_correlations) numpy.ndarray. If network_sum=False, 4D (n_templates, n_stations, n_components, n_correlations) numpy.ndarray. The number of correlations is controlled by step.

Return type:

numpy.ndarray, float

fast_matched_filter.fast_matched_filter.test_matched_filter(n_templates=1, n_stations=1, n_components=1, template_duration=10, data_duration=86400, sampling_rate=100, step=1, arch='cpu', check_zeros='first', normalize='short', network_sum=True)[source]

Test the matched_filter function.

Generate random data, templates, and moveouts, and run a matched-filter search. The templates are sliced from the data, therefore the maximum correlation coefficient should always be one if the program ran normally. Try normalize=’full’ and/or arch=’precise’ or ‘gpu’ to achieve better numerical precision.

Parameters:

  • n_templates (scalar, int, optional) – Number of synthetic templates. Default to 1.

  • n_stations (scalar, int, optional) – Number of stations. Default to 1.

  • n_components (scalar, int, optional) – Number of components/channels. Default to 1.

  • template_duration (scalar, float, optional) – Duration, in seconds, of the template waveforms. Default to 10s.

  • data_duration (scalar, float, optional) – Duration, in seconds, of the data waveforms. Default to 86400s.

  • sampling_rate (scalar, float, optional) – Sampling frequency (Hz) of the waveforms. Default to 100Hz.

  • step (scalar, int) – Time interval, in samples, between consecutive correlations.

  • arch (string, optional) – One ‘cpu’, ‘precise’ or ‘gpu’. The ‘precise’ implementation is a CPU implementation that slower but more accurate than ‘cpu’. The GPU implementation is used if arch=’gpu’. Default is ‘cpu’.

  • check_zeros (string, optional) –

    Controls the verbosity level at the end of this routine when checking zeros in the time series of correlation coefficients (CCs).

    • False: No messages.

    • ’first’: Check zeros on the first template’s CCs (recommended).

    • ’all’: Check zeros on each template’s CCs. It can be useful for

    troubleshooting but in general this would print too many messages.

    Default is ‘first’.

  • normalize (string, optional) – Either “short” or “full” - full is slower but removes the mean of the data at every correlation. Short is the original implementation. NB: When using normalize=”short”, the templates and the data sliding windows must have zero means (high-pass filter the data if necessary).

  • network_sum (boolean, default to True) – If True, returns the weighted sum of correlation coefficients across the station network. If False, returns the correlation coefficients for each channel.

Returns:

  • templates (numpy.ndarray) – (n_templates, n_stations, n_components, n_tp_samples) numpy.ndarray with the random template waveforms generated by the function.

  • moveouts (numpy.ndarray) – (n_templates, n_stations, n_components) numpy.ndarray with the random moveouts generated by the function.

  • data (numpy.ndarray) – (n_stations, n_components, n_samples) numpy.ndarray with the random data generated by the function.

  • step (scalar, int) – Time interval, in samples, between consecutive correlations.

  • cc_sums (numpy.ndarray, float) – 2D (n_templates, n_correlations) numpy.ndarray. The number of correlations is controlled by step.

  • run_time (scalar, float) – Time spent by FMF to compute the correlation coefficients.