NuRadioReco.modules.likelihood_reconstruction.neutrinoLikelihoodReconstructor module

class NuRadioReco.modules.likelihood_reconstruction.neutrinoLikelihoodReconstructor.neutrinoLikelihoodReconstructor

Bases: object

Class for reconstructing a neutrino shower in a station. This class forward-folds a simulated hadronic shower E-field calculated using the Alvarez2009 parameterization through the detector response and compares it to a data traces in the provided station object using a likelihood objective function. The -2DeltaLLH is minimized in two stages, first using a matched filter (profiling over amplitude and time) to fit the shape of the signal and second a -2DeltaLLH minimization to fine-tune the reconstructed parameters. The likelihood is calculated using the spectrum of the noise, which enables correct error estimates of reconstructed parameters.

In the current implementation of this class, the initial guess of the signal parameters needs to be very close to the true parameter values. A good guess for the vertex position can be found with interferometric vertex reconstruction modules. The time can be estimated from the peak of the trace of the reference antenna, and it is anyway profiled over in the first fitting stage. The energy probably doesn’t need a good guess, since it is also profiled over analytically in the first fitting stage. Finally, educated guesses of the neutrino arrival direction can be obtained by assuming that we observe the signal close to the Cherenkov cone (i.e., signal launch angle + ~56 deg)

For a full description of the method, see https://arxiv.org/abs/2510.21925.

Methods

begin(n_channels, n_samples, sampling_rate, ...)
run(evt, station, det, parameters_initial[, ...])	Run the likelihood reconstruction to fit a hadronic shower signal model to the traces in the station object.

begin(n_channels, n_samples, sampling_rate, noise_spectra, Vrms, config_file, detector_simulation_filter_amp=None, signal_search_width=30, n_grid_matched_filter=200, overwrite_speedup_options=True, use_chi2=False, debug=False)

Parameters:

n_channels: int

Number of channels to be used in the reconstruction

n_samples: int

Number of samples in the traces

sampling_rate: float

Sampling rate of the traces

noise_spectra: np.ndarray

Noise spectrum for each channel to be used for the likelihood calculation, i.e., sqrt(mean(abs(rfft(noise_traces))^2)). The overall normalizations of the spectra are ignored and set through the parameter Vrms.

Vrms: float

RMS of the noise in each channel. Used for the likelihood calculation

config_file: string

path to the simulation config file to use for the reconstruction signal model

detector_simulation_filter_amp: function, optional

Function to use as the _detector_simulation_filter_amp in the simulation class, e.g, hardware response and/or bandpass filter of the detector.

signal_search_width: float, optional

The width of the window to search for the signal in relative to the initial guess pulse_time. This is used as the width of the matched filter time grid, which will be profiled over in the first stage of the fit. And it is used as the bound in the final -2LLH minimization. If the peak of the signal in the trace is within the initial guess of the pulse_time +/- signal_search_width, the fit is likely to converge to a good minimum. Default: 30 * units.ns

n_grid_matched_filter: int, optional

Number of grid points to divide the matched filter time grid into. It is recommended that the matched filter time steps are at least a factor of 2 smaller than the detector sampling rate. Default: 200

overwrite_speedup_options: bool, optional

Some speedup options cause discrete jumps in the signal traces and hence the likelihood. This can cause the minimizer to get stuck in local minima and fail. The speedup options overwritten in the config file are: - delta_C_cut: set to 180 deg to not cut out the signal for any viewing angle - min_efield_amplitude: set to 0 to run the simulation for any efield amplitude - distance_cut: set to False to run simulation for any distance

use_chi2: bool, optional

Whether to use chi2 minimization instead of likelihood. Mostly used for debugging and method comparison.

debug: bool, optional

Extra plots and printouts for debugging

run(evt, station, det, parameters_initial, charge_excess_profile_id=0, use_channels=None, reference_channel=0, two_step_optimization=True, full_output=True, bounds=None)

Run the likelihood reconstruction to fit a hadronic shower signal model to the traces in the station object.

The reconstructed values are saved to the station and a shower object which is added to the station. If full_output is True, the reconstructed parameters, likelihood values, and fit p-values are returned.

Parameters:

evtNuRadioReco.framework.event.Event

The event to run the module on.

stationNuRadioReco.framework.station.Station

The station object containing the channels with the data traces.

detNuRadioReco.framework.detector.Detector

The detector description.

parameters_initialnp.ndarray

Initial guess of the parameters for the reconstruction. The array should contain seven values in the order [energy, zenith, azimuth, vertex_r_rel, vertex_theta_rel, vertex_phi_rel, pulse_time]. The first three describe the shower energy and direction, the next three describe the shower vertex relative to the reference antenna, and the last value is the approximate pulse time relative to the trace start.

charge_excess_profile_idint, optional

ID of the charge excess profile to use in the shower simulation. Not used for Alvarez2009.

use_channelslist, optional

List of channel IDs to be used for the reconstruction. If None, all channels are used.

reference_channelint, optional

Index of the reference channel for the reconstruction.

two_step_optimizationbool, optional

If True, the reconstruction performs two minimizations. The first uses a matched filter approach to profile over amplitude and time for every step of the minimization, and the fit is then fine-tuned in a second -2LLH fit. If False, the first step is skipped.

full_outputbool, optional

If True, return the reconstructed signal, the signal parameters and the minus two log-likelihood of the reconstructed signal.

boundsnp.ndarray, optional

Bounds for the parameters to reconstruct. If set to None, the default values are used: - energy: 1 PeV to 100 EeV - zenith: 0 to 180 deg - azimuth: -360 to 360 deg - vertex_r_rel: 20 m to 5 km - vertex_theta_rel: 90 to 180 deg - vertex_phi_rel: -360 to 360 deg - pulse_time: initial guess +/- self.signal_search_width

Returns:

parameters_fit: np.ndarray

The best fit parameters of the signal model. Only returned if full_output enabled

uncertainties_fit: np.ndarray

Estimated marginalized uncertainties on the 7 reconstructed parameters using the Fisher. information matrix Only returned if full_output enabled

signal_fit: np.ndarray

The reconstructed signal in the readout traces. Only returned if full_output enabled

minus_two_llh_initial: float

The minus two log-likelihood value of the initial guess parameters. Only returned if full_output enabled

minus_two_llh_fit: float

The minus two log-likelihood value of the reconstructed signal. Only returned if full_output enabled

p_value_fit: float

The goodness-of-fit p-value of the reconstructed signal. This is calculated from minus_two_llh_fit and the degrees of freedom in the likelihood_calculator. Only returned if full_output enabled