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).