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
andtime_1
, respectively. In C++ these values can be accessed through theGetTime0()
andGetTime1()
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 propertytime_window
.Each direct hits definition class has also a name, which can be accessed through the C++
GetName()
method or the Python propertyname
.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 toTrue
, 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).