Hit Multiplicity¶
The hit multiplicity 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 multiplicity cut variables:
NHitStrings
NHitDoms
NHitDomsOnePulse
NPulses
For an explaination of these variables see the documentation of the
icecube.recclasses.I3HitMultiplicityValues
class properties.
The I3HitMultiplicityCalculator icetray module¶
- class icecube.common_variables.hit_multiplicity.I3HitMultiplicityCalculator(context)
This icetray module calculates the hit multiplicity variables, e.g. NHitStrings, NHitDoms, NHitDomsOnePulse, and NPulses.
This icetray module puts an
icecube.common_variables.hit_multiplicity.I3HitMultiplicityValues
I3FrameObject, holding the calculated values, into the frame. Its name will be the one specified through the OutputI3HitMultiplicityValuesName module parameter.Module Parameters:
- PulseSeriesMapName¶
The frame object name of the pulse series map used to calculate the hit multiplicity values.
- OutputI3HitMultiplicityValuesName¶
The name of the output I3HitMultiplicityValues frame object.
- PyLogLevel¶
The Python
logging
module log level for this module.
tableio converters¶
This section lists the existing tableio converters for the hit_multiplicity sub project.
Available traysegments¶
- icecube.common_variables.hit_multiplicity.I3HitMultiplicityCalculatorSegment(tray, name, BookIt=False, **i3module_kwargs)
This tray segment adds the
icecube.common_variables.I3HitMultiplicityCalculator
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 multiplicity values.
The name of the output tableio table for the calculated multiplicity values will be the same as the name of the frame object holding the hit multiplicity values.
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 hit multiplicity values, if the “BookIt” keyword argument has been set to
True
.
- icecube.common_variables.hit_multiplicity.I3HitMultiplicityValuesBookerSegment(tray, name, OutputI3HitMultiplicityValuesName)
This traysegment generates and returns tableio converter keys to book the hit multiplicity calculation results from the frame.
The name of the output tableio table for the calculated multiplicity values will be the same as the name of the frame object holding the hit multiplicity values, e.g. the name specified through the OutputI3HitMultiplicityValuesName parameter.
- Parameters:
OutputI3HitMultiplicityValuesName (str) – The name of the
icecube.common_variables.hit_multiplicity.I3HitMultiplicityValues
object inside the frame.- Return list:
The list of tableio converter keys.
Utility functions¶
This section lists the utility functions, which are defined to calculate the hit multiplicity values.
Utility function CalculateHitMultiplicity
¶
C++ Definition:
I3HitMultiplicityValuesPtr
common_variables::hit_multiplicity::
CalculateHitMultiplicity(
const I3Geometry& geometry,
const I3RecoPulseSeriesMap& pulsesMap
);
Calculates the hit multiplicity, e.g. NHitStrings, NHitDoms, NHitDomsOnePulse, and NPulses, for the given I3Geometry, and the given I3RecoPulseSeriesMap.
Python bindings:
- icecube.common_variables.hit_multiplicity.calculate_hit_multiplicity((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map) I3HitMultiplicityValues :
Calculates the hit multiplicity values, e.g. NHitStrings, NHitDoms, NHitDomsOnePulse, and NPulses, for the given I3Geometry, and the given I3RecoPulseSeriesMap.
Examples¶
This section should give some examples how to calculate the hit multiplicity values for different use-cases.
Calculating hit multiplicity values using utility functions¶
To calculate the hit multiplicity values for a given I3RecoPulseSeriesMap using
the
calculate_hit_multiplicity()
utility function within your Python
script, you could do:
from icecube.common_variables import hit_multiplicity
geometry = frame['I3Geometry']
pulses_map = frame['my_I3RecoPulseSeriesMap']
hit_multiplicity_values = hit_multiplicity.calculate_hit_multiplicity(geometry, pulses_map)
print "Calculation results:"
print "NHitStrings : %d"%(hit_multiplicity_values.n_hit_strings)
print "NHitDoms : %d"%(hit_multiplicity_values.n_hit_doms)
print "NHitDomsOnePulse: %d"%(hit_multiplicity_values.n_hit_doms_one_pulse)
print "NPulses : %d"%(hit_multiplicity_values.n_pulses)
# Put values into the frame.
frame["MyHitMultiplicityValues"] = hit_multiplicity_values
A full script example can be found in the file
$I3_SRC/CommonVariables/resources/examples/hit_multiplicity/calculate_hit_multiplicity_values.py
.
Using the I3HitMultiplicityCalculatorSegment traysegment¶
Using the I3HitMultiplicityCalculatorSegment()
icetray traysegment to
calculate and to book hit multiplicity 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_multiplicity/I3HitMultiplicityCalculatorSegment.py
.
The following code snippet illustrates the core points:
...
from icecube import hdfwriter
from icecube.common_variables import hit_multiplicity
pulses_map_name = 'MaskedOfflinePulses'
tableio_keys_to_book = []
tableio_keys_to_book +=\
tray.AddSegment(hit_multiplicity.I3HitMultiplicityCalculatorSegment, 'hm',
PulseSeriesMapName = pulses_map_name,
OutputI3HitMultiplicityValuesName = 'HitMultiplicityValues',
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).