NuRadioReco.modules package

Subpackages

Submodules

NuRadioReco.modules.channelBandPassFilter module

class NuRadioReco.modules.channelBandPassFilter.channelBandPassFilter

Bases: object

Band pass filters the channels using different band-pass filters.

begin()
end()
get_filter(frequencies, station_id, channel_id, det, passband, filter_type, order=2)

helper function to return the filter that the module applies.

The unused parameters station_id, channel_id, det are needed to have the same signature as the get_filter functions of other modules, e.g. the hardwareResponseIncorporator.

frequencies: array of floats

the frequency array for which the filter should be returned

station_id: int

the station id

channel_id: int

the channel id

det: detector instance

the detector

passband: list or dict of lists, (default: [55 * units.MHz, 1000 * units.MHz])

passband[0]: lower boundary of filter, passband[1]: upper boundary of filter a dict can be used to specify a different bandwidth per channel, the key is the channel_id

filter_type: string or dict

‘rectangular’: perfect straight line filter ‘butter’: butterworth filter from scipy ‘butterabs’: absolute of butterworth filter from scipy or any filter that is implemented in NuRadioReco.detector.filterresponse. In this case the passband parameter is ignored or ‘FIR <type> <parameter>’ - see below for FIR filter options

a dict can be used to specify a different bandwidth per channel, the key is the channel_id

order: int (optional, default 2) or dict

for a butterworth filter: specifies the order of the filter

a dict can be used to specify a different bandwidth per channel, the key is the channel_id

array of complex floats

the complex filter amplitudes

get_filter_arguments(channel_id, passband, filter_type, order=2)
run(evt, station, det, passband=None, filter_type='rectangular', order=2)

Run the filter

evt, station, det

Event, Station, Detector

passband: list or dict of lists, (default: [55 * units.MHz, 1000 * units.MHz])

passband[0]: lower boundary of filter, passband[1]: upper boundary of filter a dict can be used to specify a different bandwidth per channel, the key is the channel_id

filter_type: string or dict

‘rectangular’: perfect straight line filter ‘butter’: butterworth filter from scipy ‘butterabs’: absolute of butterworth filter from scipy or any filter that is implemented in NuRadioReco.detector.filterresponse. In this case the passband parameter is ignored or ‘FIR <type> <parameter>’ - see below for FIR filter options

a dict can be used to specify a different bandwidth per channel, the key is the channel_id

order: int (optional, default 2) or dict

for a butterworth filter: specifies the order of the filter

a dict can be used to specify a different bandwidth per channel, the key is the channel_id

Added Jan-07-2018 by robert.lahmann@fau.de: FIR filter: see https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.get_window.html for window types; some windows need additional parameters; Default window is hamming (does not need parameters). Examples: filter_type=’FIR’ : use hamming window filter_type=’FIR hamming’: same as above filter_type=’FIR kaiser 10’ : Use Kaiser window with beta parameter 10 filter_type=’FIR kaiser’ : Use Kaiser window with default beta parameter 6

In principal, window names are just passed on to signal.firwin(), but if parameters are required, then these cases must be explicitly implemented in the code below.

The four main filter types can be implemented: LP: passband[0]=None, passband[1] = f_cut HP: passband[0]=f_cut, passband[1] = None BP: passband[0]=f_cut_low, passband[1] = f_cut_high BS: passband[0]=f_cut_high, passband[1] = f_cut_low (i.e. passband[0] > passband[1])

NuRadioReco.modules.channelGenericNoiseAdder module

class NuRadioReco.modules.channelGenericNoiseAdder.channelGenericNoiseAdder

Bases: object

Module that generates noise in some generic fashion (not based on measured data), which can be added to data.

add_random_phases(amps, n_samples_time_domain)

Adding random phase information to given amplitude spectrum.

amps: array of floats

Data that random phase is added to.

n_samples_time_domain: int

number of samples in the time domain to differentiate between odd and even number of samples

bandlimited_noise(min_freq, max_freq, n_samples, sampling_rate, amplitude, type='perfect_white', time_domain=True, bandwidth=None)

Generating noise of n_samples in a bandwidth [min_freq,max_freq].

min_freq: float

Minimum frequency of passband for noise generation min_freq = None: Only the DC component is removed. If the DC component should be included, min_freq = 0 has to be specified

max_freq: float

Maximum frequency of passband for noise generation If the maximum frequency is above the Nquist frequencey (0.5 * sampling rate), the Nquist frequency is used max_freq = None: Frequencies up to Nyquist freq are used.

n_samples: int

number of samples in the time domain

sampling_rate: float

desired sampling rate of data

amplitude: float

desired voltage of noise as V_rms (only roughly, since bandpass limited)

type: string

perfect_white: flat frequency spectrum rayleigh: Amplitude of each frequency bin is drawn from a Rayleigh distribution # white: flat frequency spectrum with random jitter

time_domain: bool (default True)

if True returns noise in the time domain, if False it returns the noise in the frequency domain. The latter might be more performant as the noise is generated internally in the frequency domain.

bandwidth: float or None (default)

if this parameter is specified, the amplitude is interpreted as the amplitude for the bandwidth specified here Otherwise the amplitude is interpreted for the bandwidth of min(max_freq, 0.5 * sampling rate) - min_freq If bandwidth is larger then (min(max_freq, 0.5 * sampling rate) - min_freq) it has the same effect as None

  • Note that by design the max frequency is the Nyquist frequency, even if a bigger max_freq is implemented (RL 17-Sept-2018)

  • Add ‘multi_white’ noise option on 20-Sept-2018 (RL)

begin(debug=False, seed=None)
end()
fftnoise_fullfft(f)

Adding random phase information to given amplitude spectrum.

f: array of floats

Data that random phase is added to.

run(event, station, detector, amplitude=0.001, min_freq=0.05, max_freq=2.0, type='perfect_white', excluded_channels=None, bandwidth=None)

Add noise to given event.

event

station

detector

amplitude: float or dict of floats

desired voltage of noise as V_rms for the specified bandwidth a dict can be used to specify a different amplitude per channel, the key is the channel_id

min_freq: float

Minimum frequency of passband for noise generation

max_freq: float

Maximum frequency of passband for noise generation If the maximum frequency is above the Nquist frequencey (0.5 * sampling rate), the Nquist frequency is used

type: string

perfect_white: flat frequency spectrum rayleigh: Amplitude of each frequency bin is drawn from a Rayleigh distribution

excluded_channels: list of ints

the channels ids of channels where no noise will be added, default is that no channel is excluded

bandwidth: float or None (default)

if this parameter is specified, the amplitude is interpreted as the amplitude for the bandwidth specified here Otherwise the amplitude is interpreted for the bandwidth of min(max_freq, 0.5 * sampling rate) - min_freq If bandwidth is larger then (min(max_freq, 0.5 * sampling rate) - min_freq) it has the same effect as None

NuRadioReco.modules.channelLengthAdjuster module

class NuRadioReco.modules.channelLengthAdjuster.channelLengthAdjuster

Bases: object

cuts the trace to detector specifications, uses a simple algorithm to determine the location of the pulse

begin(number_of_samples=256, offset=50)

Defines number of samples to cut the data to and how many samples before maximum in trace

number_of_samples: int

Number of samples desired in signal

offset: int

(roughly) How many samples before pulse

end()
run(evt, station, det)

NuRadioReco.modules.channelResampler module

class NuRadioReco.modules.channelResampler.channelResampler

Bases: object

Resamples the trace to a new sampling rate.

begin(debug=False, log_level=30)
end()
run(evt, station, det, sampling_rate)

Run the channelResampler

evt, station, det

Event, Station, Detector

sampling_rate: float

In units 1/time provides the desired sampling rate of the data.

NuRadioReco.modules.channelSignalReconstructor module

class NuRadioReco.modules.channelSignalReconstructor.channelSignalReconstructor(log_level=30)

Bases: object

Calculates basic signal parameters.

begin(debug=False, signal_window_start=None, signal_window_length=120, noise_window_start=None, noise_window_length=None)
debug: bool

Set module to debug output

signal_window_start: float or None

Start time (relative to the trace start time) of the window in which signal quantities will be calculated, with time units If None is passed as a parameter, the signal window is laid around the trace maximum

signal_window_length: float

Length of the signal window, with time units

noise_window_start: float or None

Start time (relative to the trace start time) of the window in which noise quantities will be calculated, with time units If noise_window_start or noise_window_length are None, the noise window is the part of the trace outside the signal window

noise_window_length: float or None

Length of the noise window, with time units If noise_window_start or noise_window_length are None, the noise window is the part of the trace outside the signal window

end()
get_SNR(station_id, channel, det, stored_noise=False, rms_stage=None)
station_id: int

ID of the station

channel, det

Channel, Detector

stored_noise: bool

Calculates noise from pre-computed forced triggers

rms_stage: string

See functionality of det.get_noise_RMS

SNR: dict

dictionary of various SNR parameters

run(evt, station, det, stored_noise=False, rms_stage='amp')
evt, station, det

Event, Station, Detector

stored_noise: bool

Calculates noise from pre-computed forced triggers

rms_stage: string

See functionality of det.get_noise_RMS

NuRadioReco.modules.channelStopFilter module

class NuRadioReco.modules.channelStopFilter.channelStopFilter

Bases: object

at the beginning and end of the trace (around the ‘stop’) our electronic produces a glitch this modules smoothly filters the beginning and the end of the trace

begin()
end()
run(evt, station, det, filter_size=0.1, prepend=128, append=128)
evt: Event

The event to run the module on

station: Station

The station to run the module on

det: Detector

The detector description

filter_size: size of tukey window (float)

specifies the percentage of the trace where the filter is active. default is 0.1, i.e. the first 5% and the last 5% of the trace are filtered

prepend: time interval to prepend

the time span that is filled with zeros and prepended to the trace

append: time interval to append

the time span that is filled with zeros and appended to the trace

NuRadioReco.modules.channelTemplateCorrelation module

class NuRadioReco.modules.channelTemplateCorrelation.channelTemplateCorrelation(template_directory)

Bases: object

Calculates correlation of waveform with neutrino/cr templates

begin(debug=False)
end()
match_sampling(ref_template, resampling_factor)
run(evt, station, det, channels_to_use=None, cosmic_ray=False, n_templates=1)
evt: Event

Event to run the module on

station: Station

Station to run the module on

det: Detector

The detector description

channels_to_use: List of int (default: [0, 1, 2, 3])

List of channel IDs for which the template correlation shall be calculated

cosmic_ray: bool

Switch for cosmic ray and neutrino analysis. Default is neutrino templates.

n_templates: int

default is 1: use just on standard template for all channels if n_templates is larger than one multiple templates are used and the average cross correlation for all templates is calculated. The set of templates contains several coreas input pulses and different incoming directions. The index first loops first over 6 different coreas pulses with different frequency content and then over azimuth angles of 0, 22.5 and 45 degree and then over zenith angles of 60, 50 and 70 degree

NuRadioReco.modules.channelTimeWindow module

class NuRadioReco.modules.channelTimeWindow.channelTimeWindow

Bases: object

Set trace outside time window to zero.

begin(debug=False)
end()
run(evt, station, det, window=None, window_function='rectangular', around_pulse=True, window_width=50, window_rise_time=20)
evt, station, det

Event, Station, Detector

window: list or None

[time_window_start, time_window_end] in which the signal should be kept (in units of time)

window_function: string

select window function * rectangular * hanning

around_pulse: float or None

if not None: specifies time interval around ‘signal_time’, if this option is set, ‘window’ is ignored

window_width: float

if around_pulse is set, defines the time width of the trace where the filter is 1.

window_rise_time: float

if window_function is not rectangular, defines the rise time where the filter goes from 0 to 1.

NuRadioReco.modules.correlationDirectionFitter module

class NuRadioReco.modules.correlationDirectionFitter.correlationDirectionFitter

Bases: object

Fits the direction using correlation of parallel channels.

begin(debug=False, log_level=None)
end()
run(evt, station, det, n_index=None, ZenLim=None, AziLim=None, channel_pairs=((0, 2), (1, 3)), use_envelope=False)

reconstruct signal arrival direction for all events

evt: Event

The event to run the module on

station: Station

The station to run the module on

det: Detector

The detector description

n_index: float

the index of refraction

ZenLim: 2-dim array/list of floats (default: [0 * units.deg, 90 * units.deg])

the zenith angle limits for the fit

AziLim: 2-dim array/list of floats (default: [0 * units.deg, 360 * units.deg])

the azimuth angle limits for the fit

channel_pairs: pair of pair of integers

specify the two channel pairs to use, default ((0, 2), (1, 3))

use_envelope: bool (default False)

if True, the hilbert envelope of the traces is used

NuRadioReco.modules.cosmicRayEnergyReconstructor module

class NuRadioReco.modules.cosmicRayEnergyReconstructor.cosmicRayEnergyReconstructor

Bases: object

Reconstructs the energy of an air shower from its radio signal Requires the following modules to be run beforehand:

  • a 10th order Butterworth bandpass filter with passband 80-300 MHz

  • a direction reconstruction

  • the voltageToAnalyticEfieldConverter

begin(site='mooresbay')
run(event, station, detector)

NuRadioReco.modules.efieldAirToIcePropagator module

class NuRadioReco.modules.efieldAirToIcePropagator.efieldAirToIcePropagator

Bases: object

Module that propagates the efield (usually from air showers) into the ice.

begin(debug=False)
end()
run(evt, station, det)

NuRadioReco.modules.efieldGenericNoiseAdder module

class NuRadioReco.modules.efieldGenericNoiseAdder.efieldGenericNoiseAdder

Bases: object

Module that adds noise to the electric field – such as Galactic emission and background from human communication.

begin(debug=False)
end()
run(evt, station, det, type, narrowband_freq, narrowband_power, passband)
evt: Event

The event to run the module on

station: Station

The station to run the module on

det: Detector

The detector description

type: string

narrowband: single frequency background with FM galactic: galactic emission calculated from temperature plots

narrowband_freq: list

mean frequency of one or more narrowband transmitters

narrowband_power: list

must be same size as narrowband_freq list. Each element in the list should be a list consisting of 3 elements: the power of the signal in x,y,z polarization.

passband: list

galactic background will not be simulated below the lower cutoff

NuRadioReco.modules.efieldTimeDirectionFitter module

class NuRadioReco.modules.efieldTimeDirectionFitter.efieldTimeDirectionFitter

Bases: object

Calculates basic signal parameters.

begin(debug=False, time_uncertainty=0.1)
end()
run(evt, station, det, channels_to_use=None, cosmic_ray=False)
evt: Event

The event to run the module on

station: Station

The station to run the module on

det: Detector

The detector description

channels_to_use: list of int (default: [0, 1, 2, 3])

List with the IDs of channels to use for reconstruction

cosmic_ray: Bool (default: False)

Flag to mark event as cosmic ray

NuRadioReco.modules.efieldToVoltageConverter module

class NuRadioReco.modules.efieldToVoltageConverter.efieldToVoltageConverter(log_level=30)

Bases: object

Module that should be used to convert simulations to data. It assumes that at least one efield is given per channel as input. It will convolve the electric field with the corresponding antenna response for the incoming direction specified in the channel object. The station id, defines antenna location and antenna type.

begin(debug=False, uncertainty=None, time_resolution=0.1, pre_pulse_time=200, post_pulse_time=200)

Begin method, sets general parameters of module

debug: bool

enable/disable debug mode (default: False -> no debug output)

uncertainty: dictionary (default: {})
optional argument to specify systematic uncertainties. currently supported keys

  • ‘sys_dx’: systematic uncertainty of x position of antenna

  • ‘sys_dy’: systematic uncertainty of y position of antenna

  • ‘sys_dz’: systematic uncertainty of z position of antenna

  • ‘sys_amp’: systematic uncertainty of the amplifier aplification,

    specify value as relative difference of linear gain

  • ‘amp’: statistical uncertainty of the amplifier aplification,

    specify value as relative difference of linear gain

time_resolution: float

time resolution of shifting pulse times

pre_pulse_time: float

length of empty samples that is added before the first pulse

post_pulse_time: float

length of empty samples that is added after the simulated trace

end()
run(evt, station, det)

NuRadioReco.modules.electricFieldBandPassFilter module

class NuRadioReco.modules.electricFieldBandPassFilter.electricFieldBandPassFilter

Bases: object

begin()
end()
run(evt, station, det, passband=None, filter_type='rectangular', order=2)

Applies bandpass filter to electric field

evt: event

station: station

det: detector

passband: seq, array (default: [55 * units.MHz, 1000 * units.MHz])

passband for filter, in phys units

filter_type: string

‘rectangular’: perfect straight line filter ‘butter’: butterworth filter from scipy ‘butterabs’: absolute of butterworth filter from scipy

order: int (optional, default 2)

for a butterworth filter: specifies the order of the filter

NuRadioReco.modules.electricFieldResampler module

class NuRadioReco.modules.electricFieldResampler.electricFieldResampler

Bases: object

resamples the electric field trace to a new sampling rate

begin()
end()
run(event, station, det, sampling_rate)

resample electric field

event: event

station: station

det: detector

sampling_rate: float

desired new sampling rate

NuRadioReco.modules.electricFieldSignalReconstructor module

class NuRadioReco.modules.electricFieldSignalReconstructor.electricFieldSignalReconstructor

Bases: object

Calculates basic signal parameters.

begin(signal_window_pre=10, signal_window_post=40, noise_window=100, log_level=None)
end()
run(evt, station, det, debug=False)

reconstructs quantities for electric field

evt: event

station: station

det: detector

debug: bool

set debug

NuRadioReco.modules.eventTypeIdentifier module

class NuRadioReco.modules.eventTypeIdentifier.eventTypeIdentifier

Bases: object

Use this module to distinguish cosmic ray events from neutrino events

begin()
run(event, station, mode, forced_event_type='neutrino')

Determines the type of event so that the correct modules can be executed accordingly. Currently neutrino and cosmic ray events are supported, but others can be added in the future.

event: event

station: station

mode: string

specifies which criteria the decision to flag the event as cosmic ray or neutrino should be based on. Currently only supports ‘forced’, which automatically flags the event to a specified type. Add new modes to use different criteria

forced_event_type: string

if the mode is set to forced, this is the type the event will be set to. Currently supported options are neutrino and cosmic_ray

NuRadioReco.modules.templateDirectionFitter module

class NuRadioReco.modules.templateDirectionFitter.templateDirectionFitter

Bases: object

Calculates basic signal parameters.

begin()
end()
run(evt, station, det, channels_to_use=None, cosmic_ray=False)

Fits the direction using templates

evt: event

station: station

det: detector

channels_to_use: list (default: [0, 1, 2, 3]

antenna to use for fit

cosmic_ray: bool

type to set correlation template

NuRadioReco.modules.triggerTimeAdjuster module

class NuRadioReco.modules.triggerTimeAdjuster.triggerTimeAdjuster

Bases: object

Modifies channel traces to simulate the effects of the trigger

begin(trigger_name=None, pre_trigger_time=55.0)
trigger_name: string or None

name of the trigger that should be used. If trigger_name is None, the trigger with the smalles trigger_time will be used. If a name is give, corresponding trigger module must be run beforehand. If the trigger does not exist or did not trigger, this module will do nothing

pre_trigger_time: float

Amount of time that should be stored in the channel trace before the trigger. If the channel trace is long enough, it will be cut accordingly. Otherwise, it will be rolled.

cut_trace: bool

If true, the trace will be cut to the length specified in the detector description

run(event, station, detector)

NuRadioReco.modules.voltageToAnalyticEfieldConverter module

NuRadioReco.modules.voltageToAnalyticEfieldConverter.covariance(function, vmin, up, fast=False)

Numerically compute the covariance matrix from a chi^2 or -logLikelihood function.

function: function-like

The function may accept only a vector argument and has to return a scalar.

vmin: array of floats

Position of the minimum.

up: float

Threshold value to pass when climbing uphill. up = 1 for a chi^2 function up = 0.5 for a -logLikelihood function

fast: boolean

If true invert hesse matrix at the minimum, use this if computing function is expensive.

>>> cov = ((2.0,0.2),(0.2,2.0))
>>> invcov = np.linalg.inv(cov)
>>> xs = np.array((1.0,-1.0))
>>> def ChiSquare(pars, grad = None): return np.dot(xs-pars,np.dot(invcov,xs-pars))
>>> def NegLogLike(pars, grad = None): return 0.5*ChiSquare(pars)
>>> covariance(ChiSquare, xs, 1.0)
array([[ 2. ,  0.2],
       [ 0.2,  2. ]])
>>> covariance(ChiSquare, xs, 1.0, fast=True)
array([[ 2. ,  0.2],
       [ 0.2,  2. ]])
>>> covariance(NegLogLike, xs, 0.5)
array([[ 2. ,  0.2],
       [ 0.2,  2. ]])
>>> covariance(NegLogLike, xs, 0.5, fast=True)
array([[ 2. ,  0.2],
       [ 0.2,  2. ]])

The algorithm is slow (it needs many function evaluations), but robust. The covariance matrix is derived by explicitly following the chi^2 or -logLikelihood function uphill until it crosses the 1-sigma contour.

The fast alternative is to invert the hessian matrix at the minimum.

Hans Dembinski <hans.dembinski@kit.edu>

NuRadioReco.modules.voltageToAnalyticEfieldConverter.stacked_lstsq(L, b, rcond=1e-10)

Solve L x = b, via SVD least squares cutting of small singular values L is an array of shape (…, M, N) and b of shape (…, M). Returns x of shape (…, N)

class NuRadioReco.modules.voltageToAnalyticEfieldConverter.voltageToAnalyticEfieldConverter

Bases: object

reconstucts the electric-field by foward folding an analytic pulse function through the antenna

This module works only for cosmic rays so far. The cosmic-ray radio pulse can be described in Fourier space with a simple exponential function for the magnitude as a function of frequency. The phase is set to zero. A slope in the phase spectrum corresponds to a translation in time. In each iteration step, the time shift is set to the shift that results in the maximal cross correlation.

The module also calculates the polarization angle and the energy fluence from the fit parameters.

begin()

begin method. This function is executed before the event loop.

The antenna pattern provider is initialized here.

end()
run(evt, station, det, debug=False, debug_plotpath=None, use_channels=None, bandpass=None, use_MC_direction=False)

run method. This function is executed for each event

evt station det debug: bool

if True debug plotting is enables

debug_plotpath: string or None

if not None plots will be saved to a file rather then shown. Plots will be save into the debug_plotpath directory

use_channels: array of ints (default: [0, 1, 2, 3])

the channel ids to use for the electric field reconstruction default: 0 - 3

bandpass: [float, float] (default: [100 * units.MHz, 500 * units.MHz])

the lower and upper frequecy for which the analytic pulse is calculated. A butterworth filter of 10th order and a rectangular filter is applied. default 100 - 500 MHz

use_MC_direction: bool

use simulated direction instead of reconstructed direction

NuRadioReco.modules.voltageToEfieldConverter module

NuRadioReco.modules.voltageToEfieldConverter.get_array_of_channels(station, use_channels, det, zenith, azimuth, antenna_pattern_provider, time_domain=False)
NuRadioReco.modules.voltageToEfieldConverter.stacked_lstsq(L, b, rcond=1e-10)

Solve L x = b, via SVD least squares cutting of small singular values L is an array of shape (…, M, N) and b of shape (…, M). Returns x of shape (…, N)

class NuRadioReco.modules.voltageToEfieldConverter.voltageToEfieldConverter

Bases: object

begin()
end()
run(evt, station, det, use_channels=None, use_MC_direction=False, force_Polarization='')

run method. This function is executed for each event

evt station det use_channels: array of ints (default: [0, 1, 2, 3])

the channel ids to use for the electric field reconstruction

use_MC_direction: bool

if True uses zenith and azimuth direction from simulated station if False uses reconstructed direction from station parameters.

force_Polarization: str

if eTheta or ePhi, then only reconstructs chosen polarization of electric field, assuming the other is 0. Otherwise, reconstructs electric field for both eTheta and ePhi

NuRadioReco.modules.voltageToEfieldConverterPerChannel module

class NuRadioReco.modules.voltageToEfieldConverterPerChannel.voltageToEfieldConverterPerChannel

Bases: object

Converts voltage trace to electric field per channel

Assumes either co-pole or cross-pole, then finds the electric field per channel by E = V/H in fourier space.

begin()
end()
run(evt, station, det, pol=0)

Performs computation for voltage trace to electric field per channel

Will provide a deconvoluted (electric field) trace for each channel from the stations input voltage traces

evt: event data structure

the event data structure

station: station data structure

the station data structure

det: detector object

the detector object

pol: polarization

0 = eTheta polarized, 1 = ePhi polarized

Module contents