Hit Statistics

The hit statistics sub project of CommonVariables provides C++ utility functions (with pybindings), icetray modules, tableio converters, and icetray traysegments to calculate and to book the following hit statistics variables:

  • COG

  • COGZSigma

  • MinPulseTime

  • MaxPulseTime

  • QMaxDoms

  • QTotPulses

  • ZMin

  • ZMax

  • ZMean

  • ZSigma

  • ZTravel

For an explaination of these variables see the documentation of the icecube.recclasses.I3HitStatisticsValues class properties.

The I3HitStatisticsCalculator icetray module

class icecube.common_variables.hit_statistics.I3HitStatisticsCalculator(context)

This icetray module calculates the hit statistics variables, e.g. COG, PulseTimeSpan, QMinDoms, QMaxDoms, QTotPulses, ZMean, ZSigma, and ZTravel.

This icetray module puts an icecube.common_variables.hit_statistics.I3HitStatisticsValues I3FrameObject, holding the calculated values, into the frame. Its name will be the one specified through the OutputI3HitStatisticsValuesName module parameter.

Module Parameters:

PulseSeriesMapName

The frame object name of the pulse series map used to calculate the hit statistics values.

OutputI3HitStatisticsValuesName

The name of the output I3HitStatisticsValues frame object.

PyLogLevel

The Python logging module log level for this module.

tableio converters

This section lists the existing tableio converters for the hit_statistics sub project.

Available traysegments

icecube.common_variables.hit_statistics.I3HitStatisticsCalculatorSegment(tray, name, BookIt=False, COGBookRefFrame=icecube._tableio_dataclasses.BookRefFrame.Car, **i3module_kwargs)

This tray segment adds the icecube.common_variables.I3HitStatisticsCalculator 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 traysegment should also generate and return the tableio converter keys for the calculated hit statistics values.

    The name of the output tableio table for the calculated statistics values will be the same as the name of the frame object holding the hit statistics values.

    Default value is False.

  • COGBookRefFrame (enum dataclasses.converters.I3PositionConverter.BookRefFrame) –

    The specifier of the reference frame into which the COG position should be booked.

    Default value is dataclasses.converters.I3PositionConverter.BookRefFrame.Car.

Return None:

If the “BookIt” keyword argument has been set to False.

Return list:

The list of tableio converter keys to book the hit statistics values, if the “BookIt” keyword argument has been set to True.

icecube.common_variables.hit_statistics.I3HitStatisticsValuesBookerSegment(tray, name, OutputI3HitStatisticsValuesName, COGBookRefFrame=icecube._tableio_dataclasses.BookRefFrame.Car)

This traysegment generates and returns tableio converter keys to book the hit statistics calculation results from the frame.

The name of the output tableio table for the calculated statistics values will be the same as the name of the frame object holding the hit statistics values, e.g. the name specified through the OutputI3HitStatisticsValuesName parameter.

Parameters:
  • OutputI3HitStatisticsValuesName (str) – The name of the icecube.common_variables.hit_statistics.I3HitStatisticsValues object inside the frame.

  • COGBookRefFrame (enum dataclasses.converters.I3PositionConverter.BookRefFrame) –

    The specifier of the reference frame in which the COG position values should be booked.

    Default value is dataclasses.converters.I3PositionConverter.BookRefFrame.Car.

Return list:

The list of tableio converter keys.

Utility functions

This section lists the utility functions, which are defined to calculate the hit statistics values.

Utility function CalculateHitStatistics

C++ Definition:

I3HitStatisticsValuesPtr
common_variables::hit_statistics::
CalculateHitStatistics(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_hit_statistics((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3HitStatisticsValues :

Calculates the hit statistics values for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateCOG

C++ Definition:

I3PositionPtr
common_variables::hit_statistics::
CalculateCOG(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_cog((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Position :

Calculates the Center-Of-Gravity (COG) of the event given by the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateCOGZSigma

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateCOGZSigma(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_cog_z_sigma((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the sigma value of the z-component of the Center-Of-Gravity (COG) of the event given by the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateMinPulseTime

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateMinPulseTime(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_min_pulse_time((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the minimal time of all pulses, e.g. the time of the first pulse, for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateMaxPulseTime

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateMaxPulseTime(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_max_pulse_time((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the maximal time of all pulses, e.g. the time of the last pulse, for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateQMaxDoms

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateQMaxDoms(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_q_max_doms((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the maximal value of all DOM pulse charge sums for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateQTotPulses

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateQTotPulses(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_q_tot_pulses((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the total charge of all pulses for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateZMin

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateZMin(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_z_min((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the minimal OM_Z value of all hits for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateZMax

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateZMax(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_z_max((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the maximal OM_Z value of all hits for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateZMean

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateZMean(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_z_mean((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the mean of the OM_Z values for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateZSigma

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateZSigma(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_z_sigma((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the sigma (RMSD) of the OM_Z values for the given I3Geometry, and the given I3RecoPulseSeriesMap.

Utility function CalculateZTravel

C++ Definition:

I3DoublePtr
common_variables::hit_statistics::
CalculateZTravel(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap
);

Python bindings:

icecube.common_variables.hit_statistics.calculate_z_travel((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3Double :

Calculates the ZTravel cut variable for the given I3Geometry, and the given I3RecoPulseSeriesMap. It is defined as:

\[zTravel = \frac{1}{NHitDoms}\sum_{i=1}^{NHitDoms}\left( OMz_i - \overline{OMz_{\mathrm{first\ quartile\ in\ time}}}\right)\]

where \(\overline{OMz_{\mathrm{first\ quartile\ in\ time}}}\) is the arithmetic mean of the DOM’s z-component of the first quartile of the hit DOMs sorted ascending by time. The time of each hit DOM is taken from the first pulse of this DOM:

\[\overline{OMz_{\mathrm{first\ quartile\ in\ time}}} = \frac{1}{NHitDoms/4}\sum_{j=1}^{NHitDoms/4} OMz_j\]

Note

ZTravel is only defined for \(NHitDoms >= 4\). Otherwise it returns NAN.

Examples

This section should give some examples how to calculate the hit statistics values for different use-cases.

Calculating hit statistics values using utility functions

To calculate the hit statistics values for a given I3RecoPulseSeriesMap using the calculate_hit_statistics() utility function within your Python script, you could do:

from icecube.icetray import I3Units
from icecube.common_variables import hit_statistics

geometry   = frame['I3Geometry']
pulses_map = frame['my_I3RecoPulseSeriesMap']

hit_statistics_values = hit_statistics.calculate_hit_statistics(geometry, pulses_map)

print "Calculation results:"
print "COG         : %s"%(hit_statistics_values.cog)
print "COGZSigma   : %.2f m"%(hit_statistics_values.cog_z_sigma/I3Units.m)
print "MinPulseTime: %.2f ns"%(hit_statistics_values.min_pulse_time/I3Units.ns)
print "MaxPulseTime: %.2f ns"%(hit_statistics_values.max_pulse_time/I3Units.ns)
print "QMaxDoms    : %.2f PE"%(hit_statistics_values.q_max_doms)
print "QTotPulses  : %.2f PE"%(hit_statistics_values.q_tot_pulses)
print "ZMin        : %.2f m"%(hit_statistics_values.z_min/I3Units.m)
print "ZMax        : %.2f m"%(hit_statistics_values.z_max/I3Units.m)
print "ZMean       : %.2f m"%(hit_statistics_values.z_mean/I3Units.m)
print "ZSigma      : %.2f m"%(hit_statistics_values.z_sigma/I3Units.m)
print "ZTravel     : %.2f m"%(hit_statistics_values.z_travel/I3Units.m)

# Put values into the frame.
frame["MyHitStatisticsValues"] = hit_statistics_values

A full script example can be found in the file $I3_SRC/CommonVariables/resources/examples/hit_statistics/calculate_hit_statistics_values.py.

Using the I3HitStatisticsCalculatorSegment traysegment

Using the I3HitStatisticsCalculatorSegment() icetray traysegment to calculate and to book hit statistics values is the preferred and easiest way of doing it. A full script example can be found in the file $I3_SRC/CommonVariables/resources/examples/hit_statistics/I3HitStatisticsCalculatorSegment.py. The following code snippet illustrates the core points:

...
from icecube import hdfwriter
from icecube.common_variables import hit_statistics

pulses_map_name = 'MaskedOfflinePulses'

tableio_keys_to_book = []

tableio_keys_to_book +=\
tray.AddSegment(hit_statistics.I3HitStatisticsCalculatorSegment, 'hs',
    PulseSeriesMapName              = pulses_map_name,
    OutputI3HitStatisticsValuesName = 'HitStatisticsValues',
    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).