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