NuRadioReco.utilities.trace_utilities module

This module contains utility functions to compute various observables from waveforms.

The functions in this module can be used to compute observables from waveforms, such as the energy fluence, the stokes parameters, the signal-to-noise ratio, the root power ratio, the Hilbert envelope, the impulsivity, the coherent sum, the entropy, the kurtosis, and the correlation between two traces.

All functions in this module do not depend on the NuRadioReco framework and can be used independently. The functions do not alter the input traces, but only compute observables from them.

See Also

NuRadioReco.utilities.signal_processing: Module for functions that modify traces, e.g., by filtering, delaying, etc.

NuRadioReco.utilities.trace_utilities.get_efield_antenna_factor(*args, **kwargs)[source]

NuRadioReco.utilities.trace_utilities.get_channel_voltage_from_efield(*args, **kwargs)[source]

NuRadioReco.utilities.trace_utilities.upsampling_fir(*args, **kwargs)[source]

NuRadioReco.utilities.trace_utilities.butterworth_filter_trace(*args, **kwargs)[source]

NuRadioReco.utilities.trace_utilities.apply_butterworth(*args, **kwargs)[source]

NuRadioReco.utilities.trace_utilities.delay_trace(*args, **kwargs)[source]

NuRadioReco.utilities.trace_utilities.get_electric_field_energy_fluence(electric_field_trace, times, signal_window_mask=None, noise_window_mask=None)[source]

Compute the energy fluence of an electric field trace.

Parameters:

electric_field_trace2d array: The electric field trace. The first dimension corresponds to the number of traces/polarizations, the second dimension to the number of samples.
times1d array: The times corresponding to the electric field trace.
signal_window_mask1d array, default=None: A boolean mask to select the signal window.
noise_window_mask1d array, default=None: A boolean mask to select the noise window.

Returns:

energy_fluence1d array: The energy fluence of the electric field per polarization.

NuRadioReco.utilities.trace_utilities.get_stokes(trace_u, trace_v, window_samples=128, squeeze=True)[source]

Compute the stokes parameters for electric field traces

Parameters:

trace_u1d array (float): The u component of the electric field trace
trace_v1d array (float): The v component of the electric field trace. The two components should have equal lengths, and the (u, v) coordinates should be perpendicular. Common choices are (theta, phi) or (vxB, vxvxB)
window_samplesint | None, default: 128: If not None, return a running average of the stokes parameters over window_samples. If None, compute the stokes parameters over the whole trace (equivalent to window_samples=len(trace_u)).
squeezebool, default: True: Only relevant if window_samples=None. Squeezes out the second axis (which has a length of one) and returns an array of shape (4,)

Returns:

stokes2d array of floats: The stokes parameters I, Q, U, V. The shape of the returned array is (4, len(trace_u) - window_samples +1), i.e. stokes[0] returns the I parameter, stokes[1] corresponds to Q, and so on.

Examples

For an electric field defined in (eR, eTheta, ePhi) components, the stokes parameters can be given simply by:

get_stokes(electric_field.get_trace()[1], electric_field.get_trace()[2])

To instead get the stokes parameters in vxB and vxvxB, we need to first obtain the appropriate electric field components

cs = radiotools.coordinatesystems.cstrafo(zenith, azimuth, magnetic_field_vector)

efield_trace_vxB_vxvxB = cs.transform_to_vxB_vxvxB(
    cs.transform_from_onsky_to_ground(efield.get_trace())
)

NuRadioReco.utilities.trace_utilities.peak_to_peak_amplitudes(trace, coincidence_window_size)[source]

Calculates all local peak to peak amplitudes of a given trace.

Parameters:

trace: array of floats: Array containing the trace
coincidence_window_size: int: Length along which to calculate minimum

Returns:

amplitudes: array of floats (same length as the input trace): Local peak to peak amplitudes

NuRadioReco.utilities.trace_utilities.get_split_trace_noise_RMS(trace, segments=4, lowest=2)[source]

Calculates the noise root mean square (RMS) of a given trace.

This method splits the trace into segments, then calculates the RMS of each segment, and then takes the mean of the lowest few segemts’ RMS values.

Parameters:

trace: array of floats: Array containing the trace
segments: int: Amount of segments to cut the trace int
lowest: int: Amount of lowest segment rms values to use when calculating the mean RMS end result

Returns:

noise_root_mean_square: float: The mean of the lowest few segments’ RMS values

NuRadioReco.utilities.trace_utilities.get_signal_to_noise_ratio(trace, noise_rms, window_size=3)[source]

Computes the Signal to Noise Ratio (SNR) of a given trace.

The signal to noise ratio is calculated as the peak to peak amplitude within a given window size divided by twice the noise root mean square (RMS).

Parameters:

tracearray of floats: Trace of a waveform
noise_rms: float: Noise root mean square (RMS)
window_size: int: Coincidence window size (default: 3)

Returns:

signal_to_noise_ratio: float: Signal to Noise Ratio (SNR) value

NuRadioReco.utilities.trace_utilities.get_root_power_ratio(trace, times, noise_rms)[source]

Computes the Root Power Ratio (RPR) of a given trace.

It compares the peak signal strength to the baseline noise. The waveform’s power is smoothed using a 25 ns sliding window, and the square root of this smoothed power gives the rolling root power. The RPR is the maximum root power divided by the noise RMS

Parameters:

trace: array of floats: Trace of a waveform
times: array of floats: Times of a waveform
noise_rms: float: noise root mean square (RMS)

Returns:

root_power_ratio: float: Root Power Ratio (RPR) value

NuRadioReco.utilities.trace_utilities.get_hilbert_envelope(trace)[source]

Applies the Hilbert Tranform to a given waveform trace, then it will give us an envelope trace.

Parameters:

trace: array of floats: Trace of a waveform

Returns:

envelope: array of floats: Hilbert envelope of the waveform trace

NuRadioReco.utilities.trace_utilities.get_impulsivity(trace)[source]

Calculates the impulsivity of a signal (trace).

This function computes the impulsivity of a trace by first performing the Hilbert Transform to obtain an analytic signal (Hilbert envelope) and then determining the cumulative distribution function (CDF) of the square of the sorted envelope values i.e. power values based on their closeness to the maximum value. The average of the CDF is then scaled and returned as the impulsivity value.

Parameters:

trace: array of floats: Trace of a waveform

Returns:

impulsivity: float: Impulsivity of the signal (scaled between 0 and 1)

NuRadioReco.utilities.trace_utilities.get_coherent_sum(trace_set, ref_trace, use_envelope=False)[source]

Generates the coherently-summed waveform (CSW) of a sets of traces.

This function finds the correlation between each trace from a set and the reference trace, then rolls all traces to align with the reference trace, and then add them up to get the CSW.

Parameters:

trace_set: 2-D array of floats: Traces of multiple channel waveforms without the reference trace
ref_trace: 1-D array of floats: Trace of the reference channel
use_envelope: bool: See if users would like to find the correlation between envelopes or just normal traces (default: False)

Returns:

sum_trace: 1-D array of floats: CSW of the set of traces

NuRadioReco.utilities.trace_utilities.get_entropy(trace, n_hist_bins=50)[source]

Calculates the shannon entropy (randomness measurement) of a trace.

Parameters:

trace: array of floats: Trace of a waveform
n_hist_bins: int: Number of bins for the histogram (default: 50)

Returns:

entropy: float: Shannon entropy of the signal (trace)

NuRadioReco.utilities.trace_utilities.get_kurtosis(trace)[source]

Calculates the kurtosis (tailedness) of a trace.

Parameters:

trace: array of floats: Trace of a waveform

Returns:

kurtosis: float: Kurtosis of the signal (trace)

NuRadioReco.utilities.trace_utilities.is_NAN_or_INF(trace)[source]

To see if a trace has any NAN or INF.

If there’s any NAN or any INF, this function will tell us how many points of NAN and INF there are.

Parameters:

trace: array of floats: Trace of a waveform

Returns:

is_bad_trace: bool: True if there’s any or False if the trace doesn’t have any unreadable point
npoints_NAN: int: Number of NAN points
npoints_INF: int: Number of INF points

NuRadioReco.utilities.trace_utilities.get_variable_window_size_correlation(data_trace, template_trace, window_size, sampling_rate=3.2, return_time_difference=False, debug=False)[source]

Calculate the correlation between two traces using a variable window size and matrix multiplication

Parameters:

data_trace: array: full trace of the data event
template_trace: array: full trace of the template
window_size: float: Size of the template window in nanoseconds
sampling_rate: float: sampling rate of the data and template trace
return_time_difference: boolean: if true, the time difference (for the maximal correlation value) between the starting of the data trace and the starting of the (cut) template trace is returned (returned time is in units.ns)
debug: boolean: if true, debug plots are created

Returns:

correlationarray of floats
time_difffloat, optional: The time difference of the maximal correlation value. Returned only if return_time_difference==True