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

Hit Statistics¶

The I3HitStatisticsCalculator icetray module¶

tableio converters¶

Available traysegments¶

Utility functions¶

Utility function `CalculateHitStatistics`¶

Utility function `CalculateCOG`¶

Utility function `CalculateCOGZSigma`¶

Utility function `CalculateMinPulseTime`¶

Utility function `CalculateMaxPulseTime`¶

Utility function `CalculateQMaxDoms`¶

Utility function `CalculateQTotPulses`¶

Utility function `CalculateZMin`¶

Utility function `CalculateZMax`¶

Utility function `CalculateZMean`¶

Utility function `CalculateZSigma`¶

Utility function `CalculateZTravel`¶

Examples¶

Calculating hit statistics values using utility functions¶

Using the I3HitStatisticsCalculatorSegment traysegment¶

Table of Contents

Previous topic

Next topic

This Page

Hit Statistics¶

The I3HitStatisticsCalculator icetray module¶

tableio converters¶

Available traysegments¶

Utility functions¶

Utility function CalculateHitStatistics¶

Utility function CalculateCOG¶

Utility function CalculateCOGZSigma¶

Utility function CalculateMinPulseTime¶

Utility function CalculateMaxPulseTime¶

Utility function CalculateQMaxDoms¶

Utility function CalculateQTotPulses¶

Utility function CalculateZMin¶

Utility function CalculateZMax¶

Utility function CalculateZMean¶

Utility function CalculateZSigma¶

Utility function CalculateZTravel¶

Examples¶

Calculating hit statistics values using utility functions¶

Using the I3HitStatisticsCalculatorSegment traysegment¶

Utility function `CalculateHitStatistics`¶

Utility function `CalculateCOG`¶

Utility function `CalculateCOGZSigma`¶

Utility function `CalculateMinPulseTime`¶

Utility function `CalculateMaxPulseTime`¶

Utility function `CalculateQMaxDoms`¶

Utility function `CalculateQTotPulses`¶

Utility function `CalculateZMin`¶

Utility function `CalculateZMax`¶

Utility function `CalculateZMean`¶

Utility function `CalculateZSigma`¶

Utility function `CalculateZTravel`¶