Time Characteristics¶
The time_characteristics sub project of CommonVariables provides C++ utility functions (with pybindings), icetray modules, and icetray segments to calculate and to book the following track characteristics cut variables:
TimeLengthFWHM
TimeLengthLastFirst
TimeLengthMaxGap
ZPattern
Variable Definitions¶
This section lists the definitions of the variables calculated by the
common_variables.time_characteristics
module.
TimeLengthFWHM¶
Considered are only the first pulses per DOM. These pulses are ordered in time. This variable gives the full width at half maximum of all those pulses.
TimeLengthLastFirst¶
Considered are only the first pulses per DOM. These pulses are ordered in time. This variable gives the difference between the last minus the first pulse in this order.
TimeLengthMaxGap¶
Considered are only the first pulses per DOM. These pulses are ordered in time. This variable gives the maximum gap in time between those pulses.
ZPattern¶
Considered are only the first pulses per DOM. These pulses are ordered in time. It is looped over those pulses. If a pulse is at a DOM with higher z-position than its preceeding pulses’ DOM, zpattern is enhanced by 1. If the DOM is lower in the detector, zpattern is decreased by 1. If the DOM is at the same height, nothing is done.
The I3TimeCharacteristicsCalculator icetray module¶
- class icecube.common_variables.time_characteristics.I3TimeCharacteristicsCalculator(context)
This icetray module calculates the time_characteristics cut variables for a given I3Geometry, a given I3RecoPulseSeriesMap.
The module put an I3TimeCharacteristicsCalculator I3FrameObject object into the frame having the key name, which has been specified through the module parameter OutputI3TimeCharacteristicsValuesName.
Module Parameters:
- PulseSeriesMapName¶
The frame object name of the pulse series map used to identify the hits.
- OutputI3TimeCharacteristicsValuesName¶
The name of the output I3TimeCharacteristicsValues frame object holding the calculation results.
- PyLogLevel¶
The Python
logging
module log level for this module.
Available traysegments¶
- icecube.common_variables.time_characteristics.I3TimeCharacteristicsCalculatorSegment(tray, name, BookIt=False, **i3module_kwargs)
This tray segment adds the
icecube.common_variables.track_.I3TrackCalculator
icetray module to the tray. The traysegment takes the same arguments as the icetray module does, plus the following additional keyword arguments:- Parameters:
BookIt (bool) –
The switch if this tray segment should also generate and return the tableio converter keys for the generated
icecube.common_variables.track_.I3TrackValues
frame object.The name of the output tableio table for the generated I3TrackValues frame object will be the same as the name of the I3TrackValues frame object holding the track cut variables.
Default value is
False
.- Return None:
If the “BookIt” keyword argument has been set to
False
.- Return list:
The list of tableio converter keys to book the I3TrackValues frame object, if the “BookIt” keyword argument has been set to
True
.
- icecube.common_variables.time_characteristics.I3TimeCharacteristicsValuesBookerSegment(tray, name, OutputI3TimeCharacteristicsValuesName)
This traysegment generates and returns tableio converter keys to book the I3TimeCharacteristicsValues frame object from the frame.
The parameters of this traysegment have the same types and meanings as the parameters of the
icecube.common_variables.time_characteristics.I3TimeCharacteristicsCalculator
icetray module.It will create one tableio table having the name specified through the OutputI3TimeCharacteristicsValuesName keyword argument.
- Return list:
The list of tableio converter keys.
Utility functions¶
This section lists the utility functions, which are defined to calculate the time characteristics cut variables.
Utility function CalculateTimeCharacteristics
¶
C++ Definition:
I3TimeCharacteristicsValuesPtr
common_variables::time_characteristics::
CalculateTimeCharacteristics(
const I3Geometry& geometry,
const I3RecoPulseSeriesMap& pulsesMap,
);
Examples¶
This section should give some examples how to calculate the time characteristics for different use-cases.
Calculating the time characteristics within Python¶
To calculate the time characteristics for a given I3RecoPulseSeriesMap using the
calculate_time_characteristics()
utility
function within your Python script, you could do:
from icecube.icetray import I3Units
from icecube.common_variables import time_characteristics
geometry = frame['I3Geometry']
pulses_map = frame['my_I3RecoPulseSeriesMap']
time_characteristics_values = time_characteristics.calculate_time_characteristics(
geometry,
pulses_map,
)
print "Calculation results: %s"%(time_characteristics_values)
A full script example can be found in the file
$I3_SRC/CommonVariables/resources/examples/time_characteristics/calculate_time_characteristics.py
.
Using the I3TimeCharacteristicsCalculatorSegment traysegment¶
Using the I3TimeCharacteristicsCalculatorSegment()
icetray traysegment to
calculate and to book time characteristics cut variables is the preferred and
easiest way of doing it. A full script example can be found in the file
$I3_SRC/CommonVariables/resources/examples/time_characteristics/I3TimeCharacteristicsCalculatorSegment.py
.
The following code snippet illustrates the core points:
...
from icecube.icetray import I3Units
from icecube import hdfwriter
from icecube.common_variables import time_characteristics
pulses_map_name = 'MaskedOfflinePulses'
reco_particle_name = 'MPEFit_SLC'
tableio_keys_to_book = []
tableio_keys_to_book +=\
tray.AddSegment(time_characteristics.I3TimeCharacteristicsCalculatorSegment, 'tc',
PulseSeriesMapName = pulses_map_name,
OutputI3TimeCharacteristicsValuesName = reco_particle_name+'Characteristics',
BookIt = True
)
tray.AddSegment(hdfwriter.I3HDFWriter, 'hdfwriter',
Keys = tableio_keys_to_book,
SubEventStreams = ['nullsplit'],
Output = 'my_data.hdf'
)
...
The key point here is that the BookIt keyword argument of the traysegment has
been set to True
, so it returns a list of tableio converter keys, that can
then be passed to a table writer (the hdfwriter.I3HDFWriter in the case here).