Direct Hits¶

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

NDirStrings
NDirDoms
NDirPulses
QDirPulses
NEarlyStrings
NEarlyDoms
NEarlyPulses
QEarlyPulses
NLateStrings
NLateDoms
NLatePulses
QLatePulses
DirTrackLength
DirTrackHitDistributionSmoothness

It is designed to enable the user to calculate direct hits for different direct hits definitions, e.g. different direct hits time windows. The definition of one particular class of direct hits is described by the icecube.common_variables.direct_hits.I3DirectHitsDefinition class.

The I3DirectHitsTimeWindow class¶

class icecube.common_variables.direct_hits.I3DirectHitsTimeWindow

The I3DirectHitsTimeWindow class describes the relative time window for the direct hits calculation.

The start and end time of the time window can be accessed through the class properties time_0 and time_1, respectively. In C++ these values can be accessed through the GetTime0() and GetTime1() class methods.

__init__((object)arg1, (float)time0, (float)time1) → None :¶: Constructs an I3DirectHitsTimeWindow class object with specified start and end times for that time window.

Class Properties

time_0¶: The start time of the relative direct hits time window.

time_1¶: The end time of the relative direct hits time window.

Class Methods

is_time_after_time_window((I3DirectHitsTimeWindow)arg1, (float)time) → bool :¶: Checks if the given relative time is after the relative time window.

is_time_before_time_window((I3DirectHitsTimeWindow)arg1, (float)time) → bool :¶: Checks if the given relative time is before the relative time window.

is_time_inside_time_window((I3DirectHitsTimeWindow)arg1, (float)time) → bool :¶: Checks if the given relative time is inside the relative time window.

The I3DirectHitsDefinition class¶

class icecube.common_variables.direct_hits.I3DirectHitsDefinition

The I3DirectHitsDefinition class describes a class of direct hits, e.g. the time window for the direct hits.

The I3DirectHitsTimeWindow class can be accessed through the C++ GetTimeWindow() method or the Python property time_window.

Each direct hits definition class has also a name, which can be accessed through the C++ GetName() method or the Python property name.

Class Properties

name¶: The name of the direct hits definition.

time_window¶: The icecube.common_variables.direct_hits.I3DirectHitsTimeWindow object, defining the time window of the direct hits.

The I3DirectHitsDefinitionSeries class¶

class icecube.common_variables.direct_hits.I3DirectHitsDefinitionSeries: The I3DirectHitsDefinitionSeries class is a vector of I3DirectHitsDefinition objects. Inside Python, it can be used like a normal Python list through its “append” and “extend” methods.

The I3DirectHitsCalculator icetray module¶

class icecube.common_variables.direct_hits.I3DirectHitsCalculator(context)

This icetray module calculates the common event variables for direct hits. A hit is considered direct when the time residual falls within a specified time window. The time residual is defined as the observed time of a hit minus the expected time, based on a track emitting light at the Cherenkov angle.

This module calculates many information about the direct hits of a particular direct hits time window. See the icecube.common_variables.direct_hits.I3DirectHitsValues class for the documentation of each variable.

The default time windows, which will be used when no time windows have been specified explicitly through the module parameter DirectHitsDefinitionSeries, will be determined through the function icecube.common_variables.direct_hits.get_default_definitions().

For each I3DirectHitsDefinition object inside the DirectHitsDefinitionSeries, the module puts an icecube.common_variables.direct_hits.I3DirectHitsValues I3FrameObject into the frame having a frame object key name of the following structure: {OutputI3DirectHitsValuesBaseName}{I3DirectHitsDefinition.name}.

Module Parameters:

DirectHitsDefinitionSeries¶: An I3DirectHitsDefinitionSeries object or a Python list of I3DirectHitsDefinition objects defining the time windows for the direct hits calculation.

PulseSeriesMapName¶: The frame object name of the pulse series map used to identify the hits.

ParticleName¶: The frame object name of the reconstructed particle used as track in the direct hits calculation.

OutputI3DirectHitsValuesBaseName¶: The base name of the output I3DirectHitsValues frame objects.

PyLogLevel¶: The Python logging module log level for this module.

tableio converters¶

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

Available traysegments¶

icecube.common_variables.direct_hits.I3DirectHitsCalculatorSegment(tray, name, BookIt=False, **i3module_kwargs)

This tray segment adds the icecube.common_variables.direct_hits.I3DirectHitsCalculator 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 tray segment should also generate and return the tableio converter keys for the calculated direct hits.

The name of the output tableio table for the calculated hits will be the same as the name of the frame object holding the calculation results.

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 direct hits, if the “BookIt” keyword argument has been set to True.

icecube.common_variables.direct_hits.I3DirectHitsValuesBookerSegment(tray, name, DirectHitsDefinitionSeries, OutputI3DirectHitsValuesBaseName)

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

The parameters of this traysegment have the same types and meanings as the parameters of the icecube.common_variables.direct_hits.I3DirectHitsCalculator icetray module.

For each direct hits definition, it will create one tableio table having the name structure {OutputI3DirectHitsValuesBaseName}{DirectHitsDefinition.name}.

Return list:: The list of tableio converter keys.

Utility functions¶

This section lists the utility functions, which are defined to calculate the direct hits.

Utility function `CalculateDirectHits`¶

C++ Definition 1:

I3DirectHitsValuesMapPtr
common_variables::direct_hits::
CalculateDirectHits(
    const I3DirectHitsDefinitionSeries& dhDefinitions,
    const I3Geometry&                   geometry,
    const I3RecoPulseSeriesMap&         pulsesMap,
    const I3Particle&                   particle
);

Calculates the direct hits for the given time windows (given through the I3DirectHitsDefinitionSeries object, the given I3Geometry, the given I3RecoPulseSeriesMap and the given I3Particle.

C++ Definition 2:

I3DirectHitsValuesMapPtr
common_variables::direct_hits::
CalculateDirectHits(
    const I3Geometry&           geometry,
    const I3RecoPulseSeriesMap& pulsesMap,
    const I3Particle&           particle
);

Calculates the direct hits for the default direct hits time windows (defined through the get_default_definitions() function), the given I3Geometry, the given I3RecoPulseSeriesMap and the given I3Particle.

Note

there used to be a global variable called default_definitions, this was removed in favor of get_default_definitions() because of unexpected behavior. If you have this in your script, please switch.

Python bindings:

icecube.common_variables.direct_hits.calculate_direct_hits((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map, (I3Particle)particle) → I3DirectHitsValuesMap :

Calculates the direct hits for the default direct hits time windows: (defined through the get_default_definitions() function), the given I3Geometry, the given I3RecoPulseSeriesMap, and the given I3Particle.
calculate_direct_hits( (I3DirectHitsDefinitionSeries)dh_definitions, (I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map, (I3Particle)particle) -> I3DirectHitsValuesMap :: Calculates the direct hits for the given time windows (given through the I3DirectHitsDefinitionSeries object or the Python list of I3DirectHitsDefinition objects), the given I3Geometry, the given I3RecoPulseSeriesMap and the given I3Particle.

calculate_direct_hits( (list)dh_definitions, (I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map, (I3Particle)particle) -> I3DirectHitsValuesMap

Utility function `GetDefaultDefinitions`¶

C++ Definition:

I3DirectHitsDefinitionSeries
common_variables::direct_hits::
GetDefaultDefinitions();

Gets an I3DirectHitsDefinitionSeries object with the default direct hits definitions (e.g. time windows). For the definition of that list see the description of the python-bindings of this function below!

Python bindings:

icecube.common_variables.direct_hits.get_default_definitions() → I3DirectHitsDefinitionSeries :

Gets the I3DirectHitsDefinitionSeries object with the default direct hits definitions, e.g. time windows. The following default direct hits time windows are defined:

time window “A”: [-15ns; +15ns]
time window “B”: [-15ns; +25ns]
time window “C”: [-15ns; +75ns]
time window “D”: [-15ns; +125ns]

Utility function `GetDirectHitsPulseMap`¶

C++ Definition:

I3RecoPulseSeriesMapPtr
common_variables::direct_hits::
GetDirectHitsPulseMap(
    const I3DirectHitsDefinition dhDefinition,
    const I3Geometry&            geometry,
    const I3RecoPulseSeriesMap&  pulsesMap,
    const I3Particle&            particle,
    bool                         allPulsesOfDirectDoms = false
);

Python bindings:

icecube.common_variables.direct_hits.get_direct_hits_pulse_map((I3DirectHitsDefinition)dh_definition, (I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map, (I3Particle)particle[, (bool)all_pulses_of_direct_doms=False]) → I3RecoPulseSeriesMap :

Returns an I3RecoPulseSeriesMap with the direct hit DOMs for a given direct hits definition, e.g. direct hits time window, for the given I3Geometry, the given I3RecoPulseSeriesMap, and the given I3Particle.

If the all_pulses_of_direct_doms option (default is False) is set to True, the I3RecoPulseSeries object of each direct hit DOM will contain all pulses of the original I3RecoPulseSeries of that DOM. Otherwise only the direct pulses will be included.

Utility function `GetDirectPulsesTimeResiduals`¶

C++ Definition:

I3VectorDoublePtr
common_variables::direct_hits::
GetDirectPulsesTimeResiduals(
    const I3DirectHitsDefinition dhDefinition,
    const I3Geometry&            geometry,
    const I3RecoPulseSeriesMap&  pulsesMap,
    const I3Particle&            particle
);

Python bindings:

icecube.common_variables.direct_hits.get_direct_pulses_time_residuals((I3DirectHitsDefinition)dh_definition, (I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map, (I3Particle)particle) → I3VectorDouble :: Returns an I3VectorDouble containing the time residuals of all direct pulses for a given direct hits definition, e.g. direct hits time window, for the given I3Geometry, the given I3RecoPulseSeriesMap, and the given I3Particle.

Examples¶

This section should give some examples how to calculate direct hits for different use-cases.

Calculating direct hits for the default IceCube direct hits definitions¶

To calculate the direct hits for the default direct hits definitions for a given I3RecoPulseSeriesMap and a given I3Particle using the calculate_direct_hits() utility function within your Python script, you could do:

from icecube.common_variables import direct_hits

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

direct_hits_map = direct_hits.calculate_direct_hits(geometry, pulses_map, particle)

print "NDirA:", direct_hits_map['A'].n_dir_doms
print "LDirA:", direct_hits_map['A'].dir_track_length
print "SDirA:", direct_hits_map['A'].dir_track_hit_distribution_smoothness

print "NDirB:", direct_hits_map['B'].n_dir_doms
...

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

Calculating direct hits using specific direct hits definitions¶

To calculate direct hits for a list of specific direct hits definitions, e.g. direct hits time windows, for a given I3RecoPulseSeriesMap and a given I3Particle using the calculate_direct_hits() utility function within your Python script, you could do:

from icecube.icetray import I3Units
from icecube.common_variables import direct_hits

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

dh_definitions = [
    direct_hits.I3DirectHitsDefinition("my_def_1", -10*I3Units.ns, +10*I3Units.ns),
    direct_hits.I3DirectHitsDefinition("my_def_2", -15*I3Units.ns, +70*I3Units.ns),
]

direct_hits_map = direct_hits.calculate_direct_hits(dh_definitions, geometry, pulses_map, particle)

for key in direct_hits_map.keys():
    print 'direct hits "%s":'%(key), direct_hits_map[key]

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

Using the I3DirectHitsCalculatorSegment traysegment¶

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

...
from icecube import hdfwriter
from icecube.common_variables import direct_hits

pulses_map_name    = 'MaskedOfflinePulses'
reco_particle_name = 'MPEFit_SLC'

dh_defs = direct_hits.get_default_definitions()

tableio_keys_to_book = []

tableio_keys_to_book +=\
tray.AddSegment(direct_hits.I3DirectHitsCalculatorSegment, 'dh',
    DirectHitsDefinitionSeries       = dh_defs,
    PulseSeriesMapName               = pulses_map_name,
    ParticleName                     = reco_particle_name,
    OutputI3DirectHitsValuesBaseName = reco_particle_name+'DirectHits',
    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).

Direct Hits¶

The I3DirectHitsTimeWindow class¶

The I3DirectHitsDefinition class¶

The I3DirectHitsDefinitionSeries class¶

The I3DirectHitsCalculator icetray module¶

tableio converters¶

Available traysegments¶

Utility functions¶

Utility function `CalculateDirectHits`¶

Utility function `GetDefaultDefinitions`¶

Utility function `GetDirectHitsPulseMap`¶

Utility function `GetDirectPulsesTimeResiduals`¶

Examples¶

Calculating direct hits for the default IceCube direct hits definitions¶

Calculating direct hits using specific direct hits definitions¶

Using the I3DirectHitsCalculatorSegment traysegment¶

Table of Contents

Previous topic

Next topic

This Page

Direct Hits¶

The I3DirectHitsTimeWindow class¶

The I3DirectHitsDefinition class¶

The I3DirectHitsDefinitionSeries class¶

The I3DirectHitsCalculator icetray module¶

tableio converters¶

Available traysegments¶

Utility functions¶

Utility function CalculateDirectHits¶

Utility function GetDefaultDefinitions¶

Utility function GetDirectHitsPulseMap¶

Utility function GetDirectPulsesTimeResiduals¶

Examples¶

Calculating direct hits for the default IceCube direct hits definitions¶

Calculating direct hits using specific direct hits definitions¶

Using the I3DirectHitsCalculatorSegment traysegment¶

Utility function `CalculateDirectHits`¶

Utility function `GetDefaultDefinitions`¶

Utility function `GetDirectHitsPulseMap`¶

Utility function `GetDirectPulsesTimeResiduals`¶