NuRadioReco.utilities.trace_utilities module

NuRadioReco.utilities.trace_utilities.get_efield_antenna_factor(station, frequencies, channels, detector, zenith, azimuth, antenna_pattern_provider)

Returns the antenna response to a radio signal coming from a specific direction

Parameters:

station: Station

frequencies: array of complex

frequencies of the radio signal for which the antenna response is needed

channels: array of int

IDs of the channels

detector: Detector

zenith, azimuth: float, float

incoming direction of the signal. Note that refraction and reflection at the ice/air boundary are taken into account

antenna_pattern_provider: AntennaPatternProvider

NuRadioReco.utilities.trace_utilities.get_channel_voltage_from_efield(station, electric_field, channels, detector, zenith, azimuth, antenna_pattern_provider, return_spectrum=True)

Returns the voltage traces that would result in the channels from the station’s E-field.

Parameters:

station: Station

electric_field: ElectricField

channels: array of int

IDs of the channels for which the expected voltages should be calculated

detector: Detector

zenith, azimuth: float

incoming direction of the signal. Note that reflection and refraction at the air/ice boundary are already being taken into account.

antenna_pattern_provider: AntennaPatternProvider

return_spectrum: boolean

if True, returns the spectrum, if False return the time trace

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

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.upsampling_fir(trace, original_sampling_frequency, int_factor=2, ntaps=128)

This function performs an upsampling by inserting a number of zeroes between samples and then applying a finite impulse response (FIR) filter.

Parameters:

trace: array of floats

Trace to be upsampled

original_sampling_frequency: float

Sampling frequency of the input trace

int_factor: integer

Upsampling factor. The resulting trace will have a sampling frequency int_factor times higher than the original one

ntaps: integer

Number of taps (order) of the FIR filter

Returns:

upsampled_trace: array of floats

The upsampled trace

NuRadioReco.utilities.trace_utilities.butterworth_filter_trace(trace, sampling_frequency, passband, order=8)

Filters a trace using a Butterworth filter.

Parameters:

trace: array of floats

Trace to be filtered

sampling_frequency: float

Sampling frequency

passband: (float, float) tuple

Tuple indicating the cutoff frequencies

order: integer

Filter order

Returns:

filtered_trace: array of floats

The filtered trace

NuRadioReco.utilities.trace_utilities.apply_butterworth(spectrum, frequencies, passband, order=8)

Calculates the response from a Butterworth filter and applies it to the input spectrum

Parameters:

spectrum: array of complex

Fourier spectrum to be filtere

frequencies: array of floats

Frequencies of the input spectrum

passband: (float, float) tuple

Tuple indicating the cutoff frequencies

order: integer

Filter order

Returns:

filtered_spectrum: array of complex

The filtered spectrum

NuRadioReco.utilities.trace_utilities.delay_trace(trace, sampling_frequency, time_delay, crop_trace=True)

Delays a trace by transforming it to frequency and multiplying by phases.

A positive delay means that the trace is shifted to the right, i.e., its delayed. A negative delay would mean that the trace is shifted to the left. Since this method is cyclic, the delayed trace will have unphysical samples at either the beginning (delayed, positive time_delay) or at the end (negative time_delay). Those samples can be cropped (optional, default=True).

Parameters:

trace: array of floats or `NuRadioReco.framework.base_trace.BaseTrace`

Array containing the trace

sampling_frequency: float

Sampling rate for the trace

time_delay: float

Time delay used for transforming the trace. Must be positive or 0

crop_trace: bool (default: True)

If True, the trace is cropped to remove samples what are unphysical after delaying (rolling) the trace.

Returns:

delayed_trace: array of floats

The delayed, cropped trace

dt_start: float (optional)

The delta t of the trace start time. Only returned if crop_trace is True.