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)

NuRadioReco.utilities.trace_utilities.get_channel_voltage_from_efield(*args, **kwargs)

NuRadioReco.utilities.trace_utilities.upsampling_fir(*args, **kwargs)

NuRadioReco.utilities.trace_utilities.butterworth_filter_trace(*args, **kwargs)

NuRadioReco.utilities.trace_utilities.apply_butterworth(*args, **kwargs)

NuRadioReco.utilities.trace_utilities.delay_trace(*args, **kwargs)

NuRadioReco.utilities.trace_utilities.get_electric_field_energy_fluence(electric_field_trace, times, signal_window_mask=None, noise_window_mask=None)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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.get_teager_kaiser_energy(trace)

Uses the Teager-Kaiser Energy Operator (TKEO) on a trace.

Parameters:

trace: array of floats

Trace of a waveform

Returns:

np.abs(tkeo): array of floats

TKEO of the input trace

NuRadioReco.utilities.trace_utilities.is_NAN_or_INF(trace)

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)

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