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