Analysis-oriented interface

A higher-level view of the same data: events, antennas and showers as objects, without the caller handling ROOT trees directly.

grand.aoi.event

grand.aoi.event_list

grand.aoi.antenna

grand.aoi.shower

grand.aoi.timetrace

grand.aoi.event

grand.aoi.event.GPS_ANTENNA_ORIGIN = (40.95068711, 93.96977396, 1200.0)

Origin (latitude, longitude, height) of the GRANDCS frame in which Event.fill_antennas() places GP300, GP80 and GP13 antennas computed from their GPS positions. It was an unnamed literal. It is not the run’s origin_geoid – (40.98456, 93.95225, 1200) in the GP80 files, about 3.8 km away – and nothing records why this point was chosen; which of the two the positions should use is open for the data owners (#215). Event.antennas_origin says which origin an event’s positions are in.

grand.aoi.event.profile(func)[source]

Returns func unchanged, standing in for line_profiler.profile.

line_profiler is an optional development dependency, so the decorator has to keep working when it is absent.

Parameters:

func (callable) – The function that would have been profiled.

Returns:

func itself, unmodified.

Return type:

callable

Event(_file: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, _directory: ~grand.dataio.data_handling.DataDirectory = None, event_number: int = None, run_number: int = None, _entry_number: int = None, antennas: list = None, _all_antennas: dict = None, _all_antennas_key: tuple = None, voltages: list = None, efields: list = None, shower: Shower(primary_type='', energy_em=0, energy_primary=0, Xmax=0, _Xmaxpos=CartesianRepresentation([[0.],
[0.],
[0.]]), azimuth=0, zenith=0, magnetic_field=array([0., 0., 0.]), _origin_geoid=CartesianRepresentation([[0.],
[0.],
[0.]]), _core_ground_pos=CartesianRepresentation([[0.],
[0.],
[0.]])) = None, simshower: Shower(primary_type='', energy_em=0, energy_primary=0, Xmax=0, _Xmaxpos=CartesianRepresentation([[0.],
[0.],
[0.]]), azimuth=0, zenith=0, magnetic_field=array([0., 0., 0.]), _origin_geoid=CartesianRepresentation([[0.],
[0.],
[0.]]), _core_ground_pos=CartesianRepresentation([[0.],
[0.],
[0.]])) = None, antennas_origin: tuple = None, gps_origin: object = None, L: int = 0, t_vector: ~numpy.ndarray = <factory>, is_reconstructed: bool = False, is_wave: bool = False, origin_planewave: ~numpy.ndarray = <factory>, chi2_planewave: ~numpy.ndarray = <factory>, origin_sphere: ~numpy.ndarray = <factory>, chi2_sphere: ~numpy.ndarray = <factory>, is_eas: bool = False, run_mode: ~numpy.uint32 = 0, data_source: str = 'other', data_generator: str = 'GRANDlib', data_generator_version: str = '0.1.0', site: str = 'DummySite', _origin_geoid: ~grand.geo.coordinates.CartesianRepresentation = <factory>, _t_bin_size: int = 2, trun: ~grand.dataio.run_trees.TRun = None, trunrawvoltage: ~grand.dataio.run_trees.TRunRawVoltage = None, tvoltage: ~grand.dataio.event_trees.TVoltage = None, tefield: ~grand.dataio.event_trees.TEfield = None, tshower: ~grand.dataio.event_trees.TShower = None, tsimshower: ~grand.dataio.event_trees.TShower = None, file_trun: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, file_trunrawvoltage: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, file_tvoltage: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, file_tefield: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, file_tshower: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, file_tsimshower: <_ROOTMock name='mock.TFile' id='140595425037296'> = None, is_starshape: bool = False, auto_file_close: bool = True, _run_trees: list = None, _event_trees: list = None, _trees: list = None, tefield_level: int = None, _pending_writes: list = None)

Bases: CheckedFields

A class for holding an event

Parameters:

  • event_number (int) – The current event in the file number

  • run_number (int) – The run number of the current event

  • antennas (list) – Antennas participating in the event

  • voltages (list) – Voltages from different antennas

  • efields (list) – Efields from different antennas

  • shower (Shower()) – Reconstructed shower

  • simshower (Shower()) – Simulated shower for simulations

  • antennas_origin (tuple) – (latitude, longitude, height) of the GRANDCS frame the positions in antennas are given in: the run’s origin_geoid, or GPS_ANTENNA_ORIGIN for positions computed from GPS.

  • gps_origin (object) – Origin for antenna positions computed from GPS (GP300, GP80, GP13): None for GPS_ANTENNA_ORIGIN, "run" for the run’s origin_geoid, or (latitude, longitude, height). Which one the data intend is for their owners to say; the default keeps the positions as they were.

  • L (int) – Event multiplicity

  • t_vector (np.ndarray) – Time vector - from the start of singla in first DU to the end in last DU

  • is_reconstructed (bool) – Was this event reconstructed

  • is_wave (bool) – Is this event associated to a single wave based on reconstruction

  • origin_planewave (np.ndarray) – Vector of origin of plane wave fit

  • chi2_planewave (np.ndarray) – Chi2 of plane wave fit

  • origin_sphere (np.ndarray) – Position of the source according to spherical fit

  • chi2_sphere (np.ndarray) – Chi2 of spherical fit

  • is_eas (bool) – Is this an EAS?

  • run_mode (np.uint32) – Run mode - calibration/test/physics.

  • data_source (str) – Data source, detector, sim, other

  • data_generator (str) – Data generator, gtot (in this case)

  • data_generator_version (str) – Generator version, gtot version (in this case)

  • site (str) – Site name

  • trun (TRun) – DOI’s TRun tree containing all run information

  • trunrawvoltage (TRunRawVoltage) – DOI’s TRunRawVoltage tree containing voltage run information

  • tvoltage (TVoltage) – DOI’s TVoltage/TRawVoltage tree containing voltage information

  • tefield (TEfield) – DOI’s TEfield tree containing Efield information

  • tshower (TShower) – DOI’s TShower tree containing reconstructed shower information

  • tsimshower (TShower) – DOI’s TShower tree containing simulated shower information

  • file_trun (ROOT.TFile) – TRun file

  • file_trunrawvoltage (ROOT.TFile) – TRunRawVoltage file

  • file_tvoltage (ROOT.TFile) – TVoltage file

  • file_tefield (ROOT.TFile) – TEfield file

  • file_tshower (ROOT.TFile) – TShower file

  • file_tsimshower (ROOT.TFile) – TSimShower file

  • is_starshape (bool) – Is this event a star shape?

  • auto_file_close (bool) – Close files automatically after event write? - slower writing but less maitanance by the user

  • tefield_level (int) – Analysis level of the Efield tree to read (tefield_l<level>); None takes the directory’s default

Event.event_number: int = None

The current event in the file number

Event.run_number: int = None

The run number of the current event

Event.antennas: list = None

Antennas participating in the event

Event.voltages: list = None

Voltages from different antennas

Event.efields: list = None

Efields from different antennas

Event.shower: Shower(primary_type='', energy_em=0, energy_primary=0, Xmax=0, _Xmaxpos=CartesianRepresentation([[0.0], [0.0], [0.0]]), azimuth=0, zenith=0, magnetic_field=array([0.0, 0.0, 0.0]), _origin_geoid=CartesianRepresentation([[0.0], [0.0], [0.0]]), _core_ground_pos=CartesianRepresentation([[0.0], [0.0], [0.0]])) = None

Reconstructed shower

Event.simshower: Shower(primary_type='', energy_em=0, energy_primary=0, Xmax=0, _Xmaxpos=CartesianRepresentation([[0.0], [0.0], [0.0]]), azimuth=0, zenith=0, magnetic_field=array([0.0, 0.0, 0.0]), _origin_geoid=CartesianRepresentation([[0.0], [0.0], [0.0]]), _core_ground_pos=CartesianRepresentation([[0.0], [0.0], [0.0]])) = None

Simulated shower for simulations

Event.antennas_origin: tuple = None

(latitude, longitude, height) of the GRANDCS frame the positions in antennas are given in: the run’s origin_geoid, or GPS_ANTENNA_ORIGIN for positions computed from GPS.

Event.gps_origin: object = None

Origin for antenna positions computed from GPS (GP300, GP80, GP13): None for GPS_ANTENNA_ORIGIN, "run" for the run’s origin_geoid, or (latitude, longitude, height). Which one the data intend is for their owners to say; the default keeps the positions as they were.

Event.L: int = 0

Event multiplicity

Event.t_vector: ndarray

Time vector - from the start of singla in first DU to the end in last DU

Event.is_reconstructed: bool = False

Was this event reconstructed

Event.is_wave: bool = False

Is this event associated to a single wave based on reconstruction

Event.origin_planewave: ndarray

Vector of origin of plane wave fit

Event.chi2_planewave: ndarray

Chi2 of plane wave fit

Event.origin_sphere: ndarray

Position of the source according to spherical fit

Event.chi2_sphere: ndarray

Chi2 of spherical fit

Event.is_eas: bool = False

Is this an EAS?

Event.run_mode: uint32 = 0

Run mode - calibration/test/physics.

Event.data_source: str = 'other'

Data source, detector, sim, other

Event.data_generator: str = 'GRANDlib'

Data generator, gtot (in this case)

Event.data_generator_version: str = '0.1.0'

Generator version, gtot version (in this case)

Event.site: str = 'DummySite'

Site name

Event.trun: TRun = None

DOI’s TRun tree containing all run information

Event.trunrawvoltage: TRunRawVoltage = None

DOI’s TRunRawVoltage tree containing voltage run information

Event.tvoltage: TVoltage = None

DOI’s TVoltage/TRawVoltage tree containing voltage information

Event.tefield: TEfield = None

DOI’s TEfield tree containing Efield information

Event.tshower: TShower = None

DOI’s TShower tree containing reconstructed shower information

Event.tsimshower: TShower = None

DOI’s TShower tree containing simulated shower information

Event.file_trun: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

TRun file

Event.file_trunrawvoltage: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

TRunRawVoltage file

Event.file_tvoltage: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

TVoltage file

Event.file_tefield: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

TEfield file

Event.file_tshower: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

TShower file

Event.file_tsimshower: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

TSimShower file

Event.is_starshape: bool = False

Is this event a star shape?

Event.auto_file_close: bool = True

Close files automatically after event write? - slower writing but less maitanance by the user

Event.tefield_level: int = None

Analysis level of the Efield tree to read (tefield_l<level>); None takes the directory’s default

property Event.file

A single file that contains all the TTrees

Returns:

Path of the file this event was read from or will be written to.

Return type:

str

property Event.directory

The directory the event’s trees were read from

Returns:

The directory, or None when the event was read from one file.

Return type:

DataDirectory or None

property Event.origin_geoid

Origin of the array frame

Returns:

Latitude and longitude in degrees and height in meters, as x, y and z; np.ravel gives three numbers.

Return type:

CartesianRepresentation, shape (3, 1)

Event.fill_event_from_trees(event_number=None, run_number=None, entry_number=None, simshower=False, use_trawvoltage=False, trawvoltage_channels=[0, 1, 2], init_trees=True, gp300_workaround=True, tefield_level=None)[source]

Fill this event from trees

Parameters:

  • event_number (int, optional) – Event number.

  • run_number (int, optional) – Run number.

  • entry_number (int, optional) – Entry index, instead of the pair above.

  • simshower (bool, optional) – Read the simulator-only shower tree.

  • use_trawvoltage (bool, optional) – Read raw voltages rather than calibrated ones.

  • trawvoltage_channels (sequence, optional) – Channels to read.

  • init_trees (bool, optional) – Open the trees before reading.

  • gp300_workaround (bool, optional) – Apply the GP300 antenna-ordering workaround.

  • tefield_level (int, optional) – Analysis level of the electric-field tree to read. The level is recorded in the tree’s metadata rather than in its name, so choosing one means choosing a file and needs directory to be set. Without one, the level of the open file is checked against this. None reads whatever is there.

Returns:

True when the event was found and populated.

Return type:

bool

Raises:

ValueError – When tefield_level names a level the data does not hold. Reading a different level than the one asked for would not be visible to the caller, so it is refused instead.

Event.fill_event_from_runtree(run_entry_number=None)[source]

Populates the run-level fields from the run tree.

Parameters:

run_entry_number (int, optional) – Entry to read.

Returns:

True when the entry was found.

Return type:

bool

Event.fill_event_from_runrawvoltagetree(run_entry_number=None)[source]

Populates the run-level voltage fields from the raw-voltage run tree.

Parameters:

run_entry_number (int, optional) – Entry to read.

Returns:

True when the entry was found.

Return type:

bool

Event.fill_antennas(gp300_workaround=True)[source]

Fill event’s antennas

Parameters:

gp300_workaround (bool, optional) – Apply the GP300 antenna-ordering workaround.

Event.fill_event_from_voltage_tree(use_trawvoltage=False, trawvoltage_channels=(0, 1, 2))[source]

Populates the voltage traces from the voltage tree.

Parameters:

  • use_trawvoltage (bool, optional) – Read TRawVoltage rather than TVoltage.

  • trawvoltage_channels (sequence, optional) – Which channels to read; all of them by default.

Returns:

True when traces were found.

Return type:

bool

Event.fill_event_from_efield_tree()[source]

Populates this event from the electric-field tree.

Returns:

True when the tree held data for this event.

Return type:

bool

Event.fill_event_from_shower_tree(simshower=False)[source]

Populates the shower parameters from the shower tree.

Parameters:

simshower (bool, optional) – Read TShowerSim, the simulator-only tree, rather than TShower.

Returns:

True when the shower was found.

Return type:

bool

Event.print()[source]

Prints a summary of the event, for interactive use.

Event.write(common_filename=None, shower_filename=None, efields_filename=None, voltages_filename=None, run_filename=None, overwrite=False, out_dir=None)[source]

Writes the whole event out, one file per tree kind.

Parameters:

  • common_filename (str, optional) – Single destination for every tree. When given, the per-tree names below are ignored.

  • shower_filename (str, optional) – Individual destinations for each tree.

  • efields_filename (str, optional) – Individual destinations for each tree.

  • voltages_filename (str, optional) – Individual destinations for each tree.

  • run_filename (str, optional) – Individual destinations for each tree.

  • overwrite (bool, optional) – Replace what this event’s trees would add to: with file names, the trees of those names in those files; with out_dir, the files of those tree kinds in that directory. Nothing else is removed. Without it, the event is added to what is there.

  • out_dir (str, optional) – Directory to write into.

Raises:

ValueError – If neither out_dir nor a file name is given: writing back into the files the event was read from is not supported.

Notes

Writing never changes the trees this event was read from, so the event, and the EventList it came from, can still be used afterwards. Only the trees with a file name, explicit or through common_filename, are written.

Event.write_run(filename, overwrite=False)[source]

Writes the run tree to a ROOT file.

Parameters:

  • filename (str) – Destination file; required.

  • overwrite (bool, optional) – Replace the tree of this kind in that file rather than adding to it.

Event.write_voltages(filename, overwrite=False)[source]

Writes the voltage traces to a ROOT file.

Parameters:

  • filename (str) – Destination file; required.

  • overwrite (bool, optional) – Replace the tree of this kind in that file rather than adding to it.

Event.write_efields(filename, overwrite=False)[source]

Writes the electric-field traces to a ROOT file.

Parameters:

  • filename (str) – Destination file; required.

  • overwrite (bool, optional) – Replace the tree of this kind in that file rather than adding to it.

Event.write_shower(filename, overwrite=False, tree_name='tshower')[source]

Writes the shower parameters to a ROOT file.

Parameters:

  • filename (str) – Destination file; required.

  • overwrite (bool, optional) – Replace the tree of this kind in that file rather than adding to it.

  • tree_name (str, optional) – Name of the tree to write, which selects TShower or TShowerSim.

Event.fill_run_tree(overwrite=False, filename=None)[source]

Fills the run tree from this event’s contents, ready to be written.

Parameters:

  • overwrite (bool, optional) – Replace existing entries rather than appending.

  • filename (str, optional) – File the tree belongs to.

Event.fill_voltage_tree(overwrite=False, filename=None)[source]

Fills the voltage tree from this event’s contents, ready to be written.

Parameters:

  • overwrite (bool, optional) – Replace existing entries rather than appending.

  • filename (str, optional) – File the tree belongs to.

Event.fill_efield_tree(overwrite=False, filename=None)[source]

Fills the electric-field tree from this event’s contents, ready to be written.

Parameters:

  • overwrite (bool, optional) – Replace existing entries rather than appending.

  • filename (str, optional) – File the tree belongs to.

Event.fill_shower_tree(overwrite=False, filename=None, tree_name='tshower')[source]

Fills the shower tree from this event’s contents.

Parameters:

  • overwrite (bool, optional) – Replace existing entries.

  • filename (str, optional) – File the tree belongs to.

  • tree_name (str, optional) – Which shower tree to fill.

Event.close_files()[source]

Writes and closes the files of the trees written with auto_file_close False.

Only trees this event filled for writing are written: the trees it was read from, and so the input files, are left untouched.

Event.fill_t_vector(resolution=1)[source]

Fills the event’s time vector with resolution resolution

Parameters:

resolution (float, optional) – Time step of the common axis, in nanoseconds.

Event.get_voltage_at_time(t)[source]

Get the voltage signal value in all the DUs at the given time

Parameters:

t (float) – Time, in nanoseconds.

Returns:

Voltage of each unit at that time.

Return type:

ndarray

Event.get_efield_at_time(t)[source]

Get the efield signal value in all the DUs at the given time

Parameters:

t (float) – Time, in nanoseconds.

Returns:

Electric field of each unit at that time.

Return type:

ndarray

Event.get_hilbert_voltage_at_time(t)[source]

Get the Hilbert envelope of the voltage in all the DUs at the given time

Parameters:

t (float) – Time, in nanoseconds.

Returns:

Hilbert envelope of the voltage at that time.

Return type:

ndarray

Event.get_hilbert_efield_at_time(t)[source]

Get the Hilbert envelope of the efield in all the DUs at the given time

Parameters:

t (float) – Time, in nanoseconds.

Returns:

Hilbert envelope of the field at that time.

Return type:

ndarray

grand.aoi.event.create_file_tree(target_dir, tree_name, source_tree)[source]

Returns a tree of tree_name in target_dir, copying source_tree if given.

Parameters:

  • target_dir (str) – Directory the file lives in.

  • tree_name (str) – Name of the tree to create.

  • source_tree (DataTree, optional) – Tree whose structure and metadata to copy.

Returns:

The new tree.

Return type:

DataTree

grand.aoi.event_list

class grand.aoi.event_list.EventList(inp_name, start_event=None, start_entry=None, tefield_level=None, gps_origin=None, **kwargs)[source]

Bases: object

A class giving access/iteration over multiple events

Every call to get_event(), and every step of an iteration, fills and returns the same Event object, so list(EventList(d)) holds that one object several times, showing the last event. Copy what you need from each event before reading the next.

See also

grand.aoi.event.Event

The event each iteration gives.

grand.dataio.data_handling.DataDirectory

The trees of a folder, without joining them into events.

Examples

Loop over the events of a simulation folder. The same Event object is reused, so copy out what you need rather than keeping event:

from pathlib import Path

import grand
from grand.aoi.event_list import EventList

sample = (Path(grand.__file__).parents[1]
          / "sim2root/Common/sim_Xiaodushan_20221026_000000_RUN1_CD_ZHAireS_0000")
for event in EventList(str(sample)):
    print("event %5d: zenith %5.2f deg, %2d antennas"
          % (event.event_number, event.simshower.zenith, len(event.antennas)))

event 13790: zenith 79.43 deg, 44 antennas
event  1618: zenith 51.64 deg,  5 antennas
directory: DataDirectory = None

The instance of the directory with files with TTrees containing the event.

file: <_ROOTMock name='mock.TFile' id='140595425037296'> = None

The instance of the file with TTrees containing the event.

get_event(event_number=None, run_number=None, entry_number=None, fill_event=True, **kwargs)[source]

Get specified event from the event list

Parameters:

  • event_number (int, optional) – Event number.

  • run_number (int, optional) – Run number.

  • entry_number (int, optional) – Entry index, instead of the pair above.

  • fill_event (bool, optional) – Populate the event from every tree, rather than only locating it.

Returns:

The event.

Return type:

Event

Raises:

  • ValueError – If both an entry and an event/run number are given, or a run number without an event number.

  • LookupError – If the input holds no such event.

get_number_of_events()[source]

Get the number of events in the list

Returns:

Number of events available.

Return type:

int

grand.aoi.antenna

class grand.aoi.antenna.Antenna(id: int = -1, _position: CartesianRepresentation = <factory>, _tilt: CartesianRepresentation = <factory>, _acceleration: CartesianRepresentation = <factory>, model: Any = 0)[source]

Bases: CheckedFields

A class describing a single antenna

Parameters:

  • id (int) – Antenna ID - the du_id from the trees

  • model (Any) – The antenna model

id: int = -1

Antenna ID - the du_id from the trees

model: Any = 0

The antenna model

property position

Antenna position in the array frame (GRANDCS), in meters.

x runs north (magnetic), y west and z up, from the frame’s origin; z is relative to the origin’s height, not to sea level. The origin is the event’s antennas_origin.

Returns:

The position; np.ravel(position) gives three numbers.

Return type:

CartesianRepresentation, shape (3, 1)

property tilt

Antenna tilt

Returns:

Tilt angles, in degrees.

Return type:

ndarray

property acceleration

Antenna acceleration - this comes from hardware.

Returns:

Measured acceleration components.

Return type:

ndarray

grand.aoi.shower

class grand.aoi.shower.Shower(primary_type: str = '', energy_em: float = 0, energy_primary: float = 0, Xmax: float = 0, _Xmaxpos: CartesianRepresentation = <factory>, azimuth: float = 0, zenith: float = 0, magnetic_field: ndarray = <factory>, _origin_geoid: CartesianRepresentation = <factory>, _core_ground_pos: CartesianRepresentation = <factory>)[source]

Bases: CheckedFields

A class for holding a shower

Parameters:

  • primary_type (str) – Shower primary particle type, such as proton, Fe, etc.

  • energy_em (float) – Shower from e+- (ie related to radio emission) (GeV)

  • energy_primary (float) – Total energy of the primary (including muons, neutrinos, …) (GeV)

  • Xmax (float) – Shower Xmax [g/cm2]

  • azimuth (float) – Shower azimuth, in degrees, from north toward west (NWU frame, origin at the core); the direction the shower comes from, as in TShower

  • zenith (float) – Shower zenith, in degrees (NWU frame, origin at the core); the direction the shower comes from, as in TShower

  • magnetic_field (np.ndarray) – Magnetic field parameters: Inclination, Declination, modulus

primary_type: str = ''

Shower primary particle type, such as proton, Fe, etc.

energy_em: float = 0

Shower from e+- (ie related to radio emission) (GeV)

energy_primary: float = 0

Total energy of the primary (including muons, neutrinos, …) (GeV)

Xmax: float = 0

Shower Xmax [g/cm2]

azimuth: float = 0

Shower azimuth, in degrees, from north toward west (NWU frame, origin at the core); the direction the shower comes from, as in TShower

zenith: float = 0

Shower zenith, in degrees (NWU frame, origin at the core); the direction the shower comes from, as in TShower

magnetic_field: ndarray

Inclination, Declination, modulus

Type:

Magnetic field parameters

property Xmaxpos

Shower position in the site’s reference frame

Returns:

Position of shower maximum, in meters (x north, y west, z up).

Return type:

CartesianRepresentation, shape (3, 1)

property origin_geoid

Origin of the array frame the shower’s positions are in

Returns:

Latitude and longitude in degrees and height in meters, as x, y and z.

Return type:

CartesianRepresentation, shape (3, 1)

property core_ground_pos

Position of the core on the ground in the site’s reference frame

Returns:

Shower core position at ground, in meters (x north, y west, z up).

Return type:

CartesianRepresentation, shape (3, 1)

grand.aoi.timetrace

class grand.aoi.timetrace.Timetrace3D(n_points: int = 0, time_step: float = 0, t0: datetime64 = <factory>, trigger_time: datetime64 = <factory>, t_bin_size: float = 2, du_id: int = -1, _trace: CartesianRepresentation = <factory>, t_vector: ndarray = <factory>, _hilbert_trace: CartesianRepresentation = <factory>)[source]

Bases: CheckedFields

A class for holding x,y,z single antenna traces over time

Parameters:

  • n_points (int) – The trace length

  • time_step (float) – [ns] n_points x step = total timetrace length

  • t0 (np.datetime64) – Start time of the trace as unix time with nanoseconds

  • trigger_time (np.datetime64) – Trigger time as unix time with nanoseconds

  • t_bin_size (float) – The size of the time bin - the time resolution in ns

  • du_id (int) – The Detector Unit ID

  • t_vector (np.ndarray) – The time vector [ns] - generated from the trace length, t0 and t_bin_size

n_points: int = 0

The trace length

time_step: float = 0

[ns] n_points x step = total timetrace length

t0: datetime64

Start time of the trace as unix time with nanoseconds

trigger_time: datetime64

Trigger time as unix time with nanoseconds

t_bin_size: float = 2

The size of the time bin - the time resolution in ns

du_id: int = -1

The Detector Unit ID

t_vector: ndarray

The time vector [ns] - generated from the trace length, t0 and t_bin_size

calculate_t_vector(time_offset)[source]

Calculation of the time vector - should be called manually when all the necessary parameters of the Timetrace3D are set

Parameters:

time_offset (float) – Subtracted from t0 to give the time of the first sample, in nanoseconds. Required.

get_value_at_time(time_offset)[source]

Get the signal value at a certain time. Returns 0, if nothing measured at this time

Parameters:

time_offset (float) – The time, in nanoseconds, on the axis of t_vector. (The docstring called it t.)

Returns:

The three components at the sample whose time equals time_offset exactly – there is no interpolation – or zeros if no sample falls at that time.

Return type:

ndarray, shape (3,)

get_hilbert_value_at_time(time_offset)[source]

Get the signal Hilbert envelope’s value at a certain time. Returns 0, if nothing measured at this time

Parameters:

time_offset (float) – The time, in nanoseconds, on the axis of t_vector. (The docstring called it t.)

Returns:

The three components at the sample whose time equals time_offset exactly – there is no interpolation – or zeros if no sample falls at that time.

Return type:

ndarray, shape (3,)

property trace

Trace 3D vector (x,y,z)

Returns:

The three-component trace.

Return type:

ndarray, shape (3, n_samples)

property hilbert_trace

Hilbert envelope 3D vector (x,y,z) - not defined in the hardware

Returns:

Its Hilbert envelope.

Return type:

ndarray, shape (3, n_samples)

class grand.aoi.timetrace.Voltage(n_points: int = 0, time_step: float = 0, t0: datetime64 = <factory>, trigger_time: datetime64 = <factory>, t_bin_size: float = 2, du_id: int = -1, _trace: CartesianRepresentation = <factory>, t_vector: ndarray = <factory>, _hilbert_trace: CartesianRepresentation = <factory>, is_triggered: bool = True)[source]

Bases: Timetrace3D

A class for holding voltage traces + additional information

Parameters:

  • n_points (int) – The trace length

  • time_step (float) – [ns] n_points x step = total timetrace length

  • t0 (np.datetime64) – Start time of the trace as unix time with nanoseconds

  • trigger_time (np.datetime64) – Trigger time as unix time with nanoseconds

  • t_bin_size (float) – The size of the time bin - the time resolution in ns

  • du_id (int) – The Detector Unit ID

  • t_vector (np.ndarray) – The time vector [ns] - generated from the trace length, t0 and t_bin_size

  • is_triggered (bool) – Is this a triggered trace? - not sure if it should be here or in Timetrace3D, or perhaps further up in the event

is_triggered: bool = True

Is this a triggered trace? - not sure if it should be here or in Timetrace3D, or perhaps further up in the event

class grand.aoi.timetrace.Efield(n_points: int = 0, time_step: float = 0, t0: datetime64 = <factory>, trigger_time: datetime64 = <factory>, t_bin_size: float = 2, du_id: int = -1, _trace: CartesianRepresentation = <factory>, t_vector: ndarray = <factory>, _hilbert_trace: CartesianRepresentation = <factory>, eta: float = 0, a_ratio: float = 0)[source]

Bases: Timetrace3D

A class for holding Efield traces + additional information

Parameters:

  • n_points (int) – The trace length

  • time_step (float) – [ns] n_points x step = total timetrace length

  • t0 (np.datetime64) – Start time of the trace as unix time with nanoseconds

  • trigger_time (np.datetime64) – Trigger time as unix time with nanoseconds

  • t_bin_size (float) – The size of the time bin - the time resolution in ns

  • du_id (int) – The Detector Unit ID

  • t_vector (np.ndarray) – The time vector [ns] - generated from the trace length, t0 and t_bin_size

  • eta (float) – Polarization angle of the reconstructed Efield in the shower plane [deg]

  • a_ratio (float) – Ratio of the geomagnetic to charge excess contributions

eta: float = 0

Polarization angle of the reconstructed Efield in the shower plane [deg]

a_ratio: float = 0

Ratio of the geomagnetic to charge excess contributions

exception grand.aoi.timetrace.TreeExists[source]

Bases: Exception

Raised when writing to a tree that is already present in the file.