NuRadioReco.utilities.matched_filter module
- class NuRadioReco.utilities.matched_filter.MatchedFilter(n_samples, sampling_rate, n_antennas, data_traces=None, template_traces=None, noise_power_spectral_density=None, spectra_threshold_fraction=0.01, debug=False)[source]
Bases:
objectMatched filter class for multiple antennas with equal sampling rate and trace length. Calculates the best matching time, matched filter SNR, and likelihood for a template [n_antennas, n_samples] to a data trace [n_antennas, n_samples] using the noise power spectral density.
The class currently performs the matched filter search for one data event and one signal template at a time. To repeat the search for many datasets and/or templates, the user has to set up a loop and run set_data() and/or set_template() multiple times.
See Appendix B in https://arxiv.org/abs/2510.21925 for more details.
- Parameters:
- n_samples: int
Number of samples in the traces
- sampling_rate: float
Sampling rate of the traces
- n_antennas: int
Number of antennas (channels)
- data_traces: np.ndarray, optional
Traces containing the data with shape [n_antennas, n_samples], or optionally [n_samples] for one antenna
- template_traces: np.ndarray, optional
Traces containing the template with shape [n_antennas, n_samples], or optionally [n_samples] for one antenna
- noise_power_spectral_density: np.ndarray, optional
Traces containing the noise power spectral density with shape [n_antennas, n_frequencies], or optionally [n_frequencies] for one antenna
- spectra_threshold_fraction: float, optional
The fraction of the maximum of the noise spectra to be used as threshold. Frequencies with noise spectra below this threshold are ignored in the matched filter calculation.
Methods
Calculate the matched filter SNR (or matched filter score) using the matched filter output and the template normalization factor.
Calculate the matched filter estimate of the amplitude, i.e., the factor the template has to be multiplied with to best match the data.
Calculate the matched filter delta log likelihood of the template given the data using the matched filter output, the template normalization factor, and the data normalization factor.
Get the degrees of freedom of the matched filter delta log likelihood, which is equal to two times the number of noise_psd amplitudes above the threshold.
matched_filter_search(time_shift_array[, plot])Perform the matched filter search for the template and the data to find the best matching time and matched filter output.
set_data(data_traces)Set the data traces (one event) and calculate the data normalization factor
set_noise_psd(noise_power_spectral_density)Set the noise power spectral density, which is here defined as 2*mean(abs(fft.time2freq(noise))^2)*df and has units of V^2/GHz.
set_noise_psd_from_data(noise_traces)Set the noise power spectral density using data containing purely noise.
set_noise_psd_from_spectra(spectra[, Vrms])Calculate the noise power spectral density using the spectra of the noise defined as sqrt(mean(abs(fft.time2freq(noise))^2)).
set_template(template_traces)Set the template traces (one event) and calculate the data normalization factor
- set_data(data_traces)[source]
Set the data traces (one event) and calculate the data normalization factor
- Parameters:
- data_traces: np.ndarray
Traces containing the data with shape [n_antennas, n_samples], or optionally [n_samples] for one antenna
- set_template(template_traces)[source]
Set the template traces (one event) and calculate the data normalization factor
- Parameters:
- template_traces: np.ndarray
Traces containing the template with shape [n_antennas, n_samples], or optionally [n_samples] for one antenna
- set_noise_psd(noise_power_spectral_density)[source]
Set the noise power spectral density, which is here defined as 2*mean(abs(fft.time2freq(noise))^2)*df and has units of V^2/GHz.
See self.set_noise_psd_from_data and self.set_noise_psd_from_spectra for alternative ways to set the noise PSD.
- Parameters:
- noise_power_spectral_density: np.ndarray
Traces containing the noise power spectral density with shape [n_antennas, n_frequencies], or optionally [n_frequencies] for one antenna
- set_noise_psd_from_data(noise_traces)[source]
Set the noise power spectral density using data containing purely noise.
- Parameters:
- noise_traces: np.ndarray
Traces containing the noise with shape [n_events, n_antennas, n_samples]
- set_noise_psd_from_spectra(spectra, Vrms=None)[source]
Calculate the noise power spectral density using the spectra of the noise defined as sqrt(mean(abs(fft.time2freq(noise))^2)). By specifying Vrms, the spectra normalizations of the spectra are ignored and rescale to the given Vrms values, and spectra can then be the normalized noise filters.
- Parameters:
- spectra: np.ndarray
Spectra or filters of the noise with shape [n_antennas, n_frequencies], or optionally [n_frequencies] for one antenna
- Vrms: float or np.ndarray, optional
The Vrms value(s) to which the spectra should be rescaled. If a float is given, all antennas are rescaled to the same Vrms. If an array is given it should have shape [n_antennas]. If None, the spectra normalizations are not changed.
- matched_filter_search(time_shift_array, plot=False)[source]
Perform the matched filter search for the template and the data to find the best matching time and matched filter output.
The method stores the matched filter output for later calculations of the matched filter SNR and likelihood.
- Parameters:
- time_shift_array: np.ndarray
Array of time shifts of the template to be tested. Note that often a grid with finer spacing than the sampling rate is needed.
- plot: bool (default: False)
Whether to plot the matched filter output as a function of time shift
- Returns:
- t_best: float
The best matching time shift
- matched_filter_output: float
The matched filter output at the best matching time shift
- calculate_matched_filter_SNR()[source]
Calculate the matched filter SNR (or matched filter score) using the matched filter output and the template normalization factor. If SNR >> 1, the data is likely to contain the signal template. The matched filter SNR can be seen as the matched filter score and is the relevant quantity to compare between different templates, to find the best matching template.
- Returns:
- SNR: float
The matched filter SNR, i.e. the matched filter score
- calculate_matched_filter_delta_log_likelihood(relative_to=None)[source]
Calculate the matched filter delta log likelihood of the template given the data using the matched filter output, the template normalization factor, and the data normalization factor. This is the likelihood marginalized over the signal amplitude and time.
If relative_to is None, the the “delta” refers to the constants in the log likelihood being omitted, and it can be seen as the log likelihood relative to the most probable template (the data itself). In this case, if the template describes the signal in the data and the noise PSD describes the noise, the delta log likelihood should follow a chi2 distribution with degrees of freedom equal to two times the number of noise_psd amplitudes above the threshold (see self.get_degrees_of_freedom()).
If relative_to is “zeros”, the delta log likelihood is calculated relative to a template with zeros, i.e. no signal. In this case, the delta log likelihood can be used to test the significance of the detected signal.
- Returns:
- delta_log_likelihood: float
The matched filter delta log likelihood (profiled over amplitude and time)