NuRadioReco.modules.io.RNO_G.readRNOGDataMattak module

NuRadioReco.modules.io.RNO_G.readRNOGDataMattak.get_time_offset(trigger_type)[source]

Mapping the offset between trace start time and trigger time (~ signal time). Temporary use hard-coded values for each trigger type. In the future this information might be time, station, and channel dependent and should come from a database (or is already calibrated in mattak)

Current values motivated by figures posted in PR https://github.com/nu-radio/NuRadioMC/pull/519

Parameters:
trigger_type: str

Trigger type encoded as string from Mattak

Returns:
time_offset: float

trace_start_time = trigger_time - time_offset

class NuRadioReco.modules.io.RNO_G.readRNOGDataMattak.readRNOGData(run_table_path=None, load_run_table=True, log_level=0)[source]

Bases: object

Reader for RNO-G .root files

This class provides read access to RNO-G .root files and converts them to NuRadioMC Events. Requires mattak (https://github.com/RNO-G/mattak) to be installed.

Parameters:
run_table_path: str | None

Path to a run_table.csv file. If None, the run table is queried from the DB. (Default: None)

load_run_table: bool

If True, try to load the run_table from run_table_path. Otherwise, skip this.

log_level: enum

Set verbosity level of logger. If logging.DEBUG, set mattak to verbose (unless specified in mattak_kwargs). (Default: logging.NOTSET, ie adhere to general log level)

Examples

reader = readRNOGDataMattak.readRNOGData() # initialize reader
reader.begin('/path/to/root_file_or_folder')

evt = reader.get_event_by_index(0) # returns the first event in the file
# OR
evt = reader.get_event(run_nr=1100, event_id=679) # returns the event with run_number 1100 and event_id 679
# OR
for evt in reader.run(): # loop over all events in file
    # perform some analysis
    pass

Methods

add_selectors(selectors[, select_triggers])

Add selectors (Callable(eventInfo) -> bool) to an internal list of selectors.

begin(dirs_files[, read_calibrated_data, ...])

Parameters:

get_event(run_nr, event_id)

Allows to read a specific event identifed by run number and event id

get_event_by_index(event_index)

Allows to read a specific event identifed by its index

get_events_information([keys])

Return information of events from the EventInfo.

get_waveforms([apply_baseline_correction, ...])

Return waveforms of events passing the selectors which may have been specified

run()

Loop over all events.

end

begin(dirs_files, read_calibrated_data=False, select_triggers=None, select_runs=False, apply_baseline_correction='approximate', convert_to_voltage=True, selectors=[], run_types=['physics'], run_time_range=None, max_trigger_rate=0.0, mattak_kwargs={}, overwrite_sampling_rate=None, max_in_mem=256)[source]
Parameters:
dirs_files: str, list(str)

Path to run directories (i.e. “…/stationXX/runXXX/”) or path to root files (have to be “combined” mattak files).

read_calibrated_data: bool

If True, read calibrated waveforms from Mattak.Dataset. If False, read “raw” ADC traces. (temp. Default: False, this can/should be switched once the calibration in incorp. into Mattak)

select_triggers: str or list(str)

Names of triggers which should be selected. Convinence interface instead of passing a selector (see “selectors” below). (Default: None)

select_runs: bool

If True, use information in run_table to select runs (based on run_type, run_time, trigger_rate, …). If the run_table is not available no selection is performed (and the programm is not interrupted, only an error message is raised). See parameters to configure run selection. (Default: False)

Other Parameters:
apply_baseline_correction: ‘fit’ | ‘approximate’ | ‘median’ | ‘none’

Removes the DC (baseline) block offsets (pedestals). Options are, in order of decreasing precision and increasing performance:

  • ‘fit’ : do a full out-of-band fit to determine the block offsets; for more details, see NuRadioReco.modules.RNO_G.channelBlockOffsetFitter (slow)

  • ‘approximate’ : estimate block offsets by looking at the low-pass filtered trace (default)

  • ‘median’ : subtract the median of each block (faster)

  • ‘none’ : do not apply a baseline correction (fastest)

convert_to_voltage: bool

Only applies when non-calibrated data are read. If true, convert ADC to voltage. (Default: True)

selectors: list of lambdas

List of lambda(eventInfo) -> bool to pass to mattak.Dataset.iterate to select events. Example: trigger_selector = lambda eventInfo: eventInfo.triggerType == “FORCE” (Default: [])

run_types: list

Used to select/reject runs from information in the RNO-G RunTable. List of run_types to be used. (Default: [‘physics’])

run_time_range: tuple

Specify a time range to select runs (it is sufficient that runs cover the time range partially). Each value of the tuple has to be in a format which astropy.time.Time understands. A value can be None which means that the lower or upper bound is unconstrained. If run_time_range is None no time selection is applied. (Default: None)

max_trigger_rate: float

Used to select/reject runs from information in the RNO-G RunTable. Maximum allowed trigger rate (per run) in Hz. If 0, no cut is applied. (Default: 1 Hz)

mattak_kwargs: dict

Dictionary of arguments for mattak.Dataset.Dataset. (Default: {}) Example: Select a mattak “backend”. Options are “auto”, “pyroot”, “uproot”. If “auto” is selected, pyroot is used if available otherwise a “fallback” to uproot is used. (Default: “auto”)

overwrite_sampling_rate: float

Set sampling rate of the imported waveforms. This overwrites what is read out from runinfo (i.e., stored in the mattak files) only when the stored sampling rate is invalid (i.e. 0 or None). If None, nothing is overwritten and the sampling rate from the mattak file is used. (Default: None) NOTE: This option might be necessary when old mattak files are read which have this not set.

max_in_mem: int

Set the maximum number of events that can be stored in memory. The datareader will divide the data in batches based on this number. NOTE: This is only relevant for the mattak uproot backend

add_selectors(selectors, select_triggers=None)[source]

Add selectors (Callable(eventInfo) -> bool) to an internal list of selectors. They are used for event filtering.

Parameters:
selectors: list of Callables

List of Callable(eventInfo) -> bool to pass to mattak.Dataset.iterate to select events. Example: trigger_selector = lambda eventInfo: eventInfo.triggerType == “FORCE”

select_triggers: str or list(str)

Names of triggers which should be selected. Convenience interface instead of passing a selector. (Default: None)

get_events_information(keys=['station', 'run', 'eventNumber'])[source]

Return information of events from the EventInfo. Only information of events passing the selectors, which may have been specified, are returned.

This function is useful to make a pre-selection of events before actually reading them in combination with self.read_event().

Parameters:
keysstr or list(str) or None

List of the information to receive from each event. Have to match the attributes (member variables) of the mattak.Dataset.EventInfo class (examples are “station”, “run”, “triggerTime”, “triggerType”, “eventNumber”, …).

If None, read in all keys present in the EventInfo class. (Default: [“station”, “run”, “eventNumber”])

Returns:
data: dict

Keys of the dict are the event indecies (as used in self.read_event(event_index)). The values are dictinaries them self containing the information specified with “keys” parameter.

get_waveforms(apply_baseline_correction=None, max_events=1000)[source]

Return waveforms of events passing the selectors which may have been specified

Parameters:
apply_baseline_correction: str | None

If not None, apply a different baseline correction algorithm than specified in the begin method. Otherwise (default), use the same setting as specified there.

max_eventsint | None

The maximum number of waveforms to return.

If None, return all waveforms in all datasets. Note that this may cause a crash due to memory overflow if too many waveforms are selected.

Default: 1000

Returns:
wfs: np.array

Waveforms of all “selected” events. The wavefroms are either calibrated or not based on the class config.

run()[source]

Loop over all events.

Yields:
evt: NuRadioReco.framework.event.Event
get_event_by_index(event_index)[source]

Allows to read a specific event identifed by its index

Parameters:
event_index: int

The index of a particluar event. The index is the chronological number from 0 to number of total events (across all datasets).

Returns:
evt: NuRadioReco.framework.event.Event
get_event(run_nr, event_id)[source]

Allows to read a specific event identifed by run number and event id

Parameters:
run_nr: int

Run number

event_id: int

Event Id

Returns:
evt: NuRadioReco.framework.event.Event
end()[source]