NuRadioReco.modules.impulsiveSignalReconstructor module

Tools to reconstruct ‘generic’ impulsive signals

This module contains several helper functions and one class to reconstruct the arrival times / arrival direction of ‘generic’ impulsive signals (impulsive signals where the signal shape is not known in advance, e.g. wind-induced events).

Overview

find_threshold_crossing

Finds the times where the hilbert envelope of a trace first crosses a given threshold.

find_threshold_crossing_from_stft

Similar to find_threshold_crossing, but uses a short-time Fourier transform (STFT) to allow for power dispersion in the system. This function also supports the use of a coincidence window.

get_dt_correlation

Determines the time lag between channels using cross-correlation. Alternatively, the channels can be cross-correlated with a given template, instead.

ImpulsiveSignalReconstructor

A class that implements a full plane-wave direction reconstruction using the above methods, with the usual run method.

NuRadioReco.modules.impulsiveSignalReconstructor.find_threshold_crossing(channels, threshold=None, offset=5, min_amp=0, debug=False)

Find the time where the hilbert envelope of a trace first crosses some threshold

Parameters:

channelslist of NuRadioReco.framework.channel.Channel objects

the channels to use in the reconstruction

thresholdfloat | str | None, optional

• If a float, the threshold value.

• If the string “max”, the times of the hilbert envelope maxima are returned.

• Otherwise, if not specified (default), attempts to estimate the noise distribution and sets the threshold to the 90th percentile.

offsetfloat or list of floats, optional

Time at the start and end of each trace to exclude. If a list, the entries are the offsets for the start and end of the trace, respectively. By default, the first and last 5 ns of each trace are excluded, to avoid spurious peaks in the hilbert envelope resulting from the assumed periodicity of the trace.

min_ampfloat, optional

Minimum amplitude for a trace to be considered valid. If the maximum amplitude of a channel does not exceed min_amp, no threshold crossing will be returned for this channel.

debugbool, default False

If True, create some debug plots

Returns:

threshold_timesnp.ndarray of floats

An array with the threshold crossing times for each channel. For channels that do not exceed threshold (or min_amp), this will be np.nan.

NuRadioReco.modules.impulsiveSignalReconstructor.find_threshold_crossing_from_stft(channels, max_delta_t=50, passband=None, *, window=('tukey', 0.1), use_maximum=False, false_positive_rate=0.05, debug=False)

Find the start time of a pulse in multiple channels.

Uses a short-time fourier transform (STFT) to effectively integrate the power across multiple frequency bins, and subsequently look for coincident threshold crossings across multiple channels.

Parameters:

channelslist of NuRadioReco.framework.channel.Channel objects

the channels to use in the reconstruction

max_delta_tfloat, default: 50 * units.ns

The coincidence window between all channels. Only threshold crossings that fall within a maximum time span of max_delta_t will be selected.

passbandtuple of 2 floats, optional

The low- and high-pass frequencies of the passband to apply before correlating. If not provided, defaults to [60 MHz, 750 MHz]

windowstr or tuple, optional

Arguments to pass to scipy.signal.get_window to determine which window to use in the STFT. Defaults to ('tukey', 0.1)

Returns:

threshold_times: np.ndarray of floats

An array with the threshold crossing times for each channel

Other Parameters:

use_maximumbool, default: False

If True, considers only local maxima (instead of threshold crossing) to determine pulse times and coincidences.

false_positive_ratefloat, default 0.05

(Approximately) the expected false-positive rate at which pure noise would exceed the threshold to be considered a signal. Larger values increase the sensitivity to low-SNR signals but are more likely to tag random noise fluctuations as a signal.

debugbool or str, default: False

If True, produce some debug plots and show them. If a string, should specify a path to save the debug plots to.

Notes

This function will return the first threshold crossing but maximizes the number of channels included. E.g. if there is a 2-fold coincidence and a 3-fold coincidence at different times, the times of the 3-fold coincidence will be returned; if there are multiple possible 3-fold coincidences, only the first 3-fold coincidence will be returned.

NuRadioReco.modules.impulsiveSignalReconstructor.get_dt_correlation(channels, pos, passband=None, n_index=1.000293, templates=None, full_output=False)

Determines the time delay between 3 channels using correlation

Cross-correlates all channels and determines the relative time delays between them from the peaks in the cross-correlation. The maximum time delay between channels is restricted by the distance between them and the refractive index.

Warning

This function currently only works if exactly 3 channels are specified, and will raise an error otherwise.

Parameters:

channelslist of 3 NuRadioReco.framework.channel.Channel objects

The 3 channels to obtain the cross-correlation from.

poslist

The positions of the channels

passbandtuple of 2 floats

The low- and high-pass frequencies of the passband to apply before correlating. If not provided, defaults to [60 MHz, 750 MHz]

n_indexfloat, optional

Used to compute the maximum allowed time delay between two channels; time delays larger than the travel time of light are excluded. Default: 1.000293 (refractive index of air)

templatesNone | 1dim or 2dim array of floats, optional

If no template is provided, the channel traces are cross-correlated directly with each other. Otherwise, if a template is provided, the channel traces are correlated with the template. If multiple templates are provided, each channel is correlated with all templates, and the maximum value at each time step is used.

full_outputbool, default: False

If True, additionally return the correlation values for each channel.

Returns:

dtarray of floats

The time delays that maximize the correlation; has the same shape as channels

corrarray of floats, optional

Only if full_output==True. The correlation at dt for each channel

class NuRadioReco.modules.impulsiveSignalReconstructor.ImpulsiveSignalReconstructor

Bases: object

Class to reconstruct the direction of impulsive signals

Methods

begin()	Unused
end()	Unused
run(evt, station, det, use_channels[, ...])	Run the direction reconstruction

Initialize class

Methods

begin()	Unused
end()	Unused
run(evt, station, det, use_channels[, ...])	Run the direction reconstruction

begin()

Unused

run(evt, station, det, use_channels, method='stft', n_index=1.000293, **kwargs)

Run the direction reconstruction

Parameters:

eventEvent

Event to reconstruct (unused)

stationStation

Station that contains the channels to use in the reconstruction

detDetector

Detector description

use_channelslist

List of channel ids to use for the reconstruction

Warning

For most values of method, the reconstruction will work only if 3 channels are used. If provided more than 3 channels, the reconstruction will either ignore any additional channels, or raise an error.

methodstr, default=’stft’

Which method to use to estimate the pulse arrival times:

• 'simple_threshold': use simple threshold crossings, using the find_threshold_crossing function;

• 'xcorr': use pairwise cross-correlation or correlation with a template, using get_dt_correlation;

• 'stft' (default): uses an short-time Fourier transform (STFT) approach to identify the start of the pulse (see find_threshold_crossing_from_stft)

n_indexfloat, default 1.000293

The refractive index of the antennas. Note that the returned zenith is always computed in air, i.e. if a different refractive index is specified the refraction from air to ice is accounted for.

**kwargs

Additional keyword arguments passed to the function that determines the pulse arrival times (see method)

Returns:

zenithfloat

The reconstructed zenith. If n_index != 1 (e.g. for in-ice antennas), the returned zenith is the in-air zenith of the signal (i.e. refraction into the ice is accounted for).

azimuthfloat

The reconstructed azimuth

Notes

The reconstructed parameters are stored in the station passed to the run function. An analytic plane wave fit is used: this means

1. if <= 3 channels are used, always the solution coming from above is returned, rather than the one coming from below;

2. If no analytic solution exists for the inferred pulse arrival times, the reconstruction will fail

end()

Unused