Track Characteristics¶
The track_characteristics sub project of CommonVariables provides C++ utility functions (with pybindings), icetray modules, and icetray segments to calculate and to book the following track characteristics cut variables:
AvgDomDistQTotDom (formerly named “AvgDistQ”)
EmptyHitsTrackLength (formerly named “LEmpty”)
TrackHitsSeparationLength (formerly named “Separation”)
TrackHitsDistributionSmoothness
Note
The TrackHitsDistributionSmoothness value [-1;+1]
describes how
uniformly the hits of a given I3RecoPulseSeriesMap are distributed along the
track (given by its I3Particle object), where 0 means uniformly distributed.
The I3Cuts implementation of this cut variable is wrong if there are more than only one pulse in a I3RecoPulseSeries, because it takes the hit distances along the track (which depends only on the DOM position) for every pulse of a DOM and not only once!
The implementation of the TrackHitsDistributionSmoothness cut variable of this CommonVariables sub project takes the hit distance along the track only once for a DOM.
The current version of the code only calculates a value for at least 3 hits, in every other case, NaN is returned.
Variable Definitions¶
This section lists the definitions of the variables calculated by the
common_variables.track_characteristics
module.
Note
All variables consider only pulses which are within the configured cylinder radius around the configured track!
So the mathematical variable \(NHitDoms\) in this sub project denotes the number of hit DOMs within the configured cylinder radius around the configured track.
AvgDomDistQTotDom¶
The average DOM distance from the track weighted by the total charge of each DOM. It is calculated using the following formula:
where \(QTotDom_i\) is the total charge of the i’th DOM and \(dist(Dom_i,Track)\) is the closest approach distance of the i’th DOM to the configured track.
EmptyHitsTrackLength¶
The maximal track length of the track, which got no hits from hit DOMs within the specified cylinder radius around the track.
Note
This variable is only defined for \(NHitDoms \geq 2\). Otherwise this
variable is set to NAN
.
The algorithm to obtain this variable can be described as follows:
First a list of the projected position of the hit DOMs is created.
where \(distAlongTrack(Dom_i, Track)\) is the projected position of the i’th DOM on the line of the configured track, where \(i\) goes from \(1\) to \(NHitDoms\).
Then this distance list is sorted in ascending order:
The EmptyHitsTrackLength variable is then simply the maximal difference of successive distance elements of the sorted distance list:
where \(i\) goes from \(1\) to \(NHitDoms-1\).
TrackHitsDistributionSmoothness¶
The TrackHitsDistributionSmoothness is the maximum relative deviation of the pulses from a unifrom distribution along the track.
Be \(l_i\) the length of the track to the \(i\) th pulse in regard to the first pulse in the sorted distance list:
with \(j\) being the pulse with:
The first and the last (\(n\) th) pulse are ignored.
TrackHitsSeparationLength¶
Calculates the COG of the first quarter of hits (hits are sorted by time) and the COG of the last quarter of hits. TrackHitsSeparationLength is then the distance between the projection of the two COGs onto the LineFit.
The I3TrackCharacteristicsCalculator icetray module¶
- class icecube.common_variables.track_characteristics.I3TrackCharacteristicsCalculator(context)
This icetray module calculates the track characteristics cut variables for a given I3Geometry, a given I3RecoPulseSeriesMap, and a given track (given through an I3Particle object).
The module put an I3TrackCharacteristicsValues I3FrameObject object into the frame having the key name, which has been specified through the module parameter OutputI3TrackCharacteristicsValuesName.
Module Parameters:
- 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 for the calculation of the track characteristics.
- OutputI3TrackCharacteristicsValuesName¶
The name of the output I3TrackCharacteristicsValues frame object holding the calculation results.
- TrackCylinderRadius¶
The cylinder radius around the track. Only pulses within this cylinder radius around the track will be considered for the calculation of the track characteristics variables.
- PyLogLevel¶
The Python
logging
module log level for this module.
Available traysegments¶
- icecube.common_variables.track_characteristics.I3TrackCharacteristicsCalculatorSegment(tray, name, BookIt=False, **i3module_kwargs)
This tray segment adds the
icecube.common_variables.track_characteristics.I3TrackCharacteristicsCalculator
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 generated
icecube.common_variables.track_characteristics.I3TrackCharacteristicsValues
frame object.The name of the output tableio table for the generated I3TrackCharacteristicsValues frame object will be the same as the name of the I3TrackCharacteristicsValues frame object holding the track characteristics cut variables.
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 I3TrackCharacteristicsValues frame object, if the “BookIt” keyword argument has been set to
True
.
- icecube.common_variables.track_characteristics.I3TrackCharacteristicsValuesBookerSegment(tray, name, OutputI3TrackCharacteristicsValuesName)
This traysegment generates and returns tableio converter keys to book the I3TrackCharacteristicsValues frame object from the frame.
The parameters of this traysegment have the same types and meanings as the parameters of the
icecube.common_variables.track_characteristics.I3TrackCharacteristicsCalculator
icetray module.It will create one tableio table having the name specified through the OutputI3TrackCharacteristicsValuesName keyword argument.
- Return list:
The list of tableio converter keys.
Utility functions¶
This section lists the utility functions, which are defined to calculate the track characteristics cut variables.
Utility function CalculateTrackCharacteristics
¶
C++ Definition:
I3TrackCharacteristicsValuesPtr
common_variables::track_characteristics::
CalculateTrackCharacteristics(
const I3Geometry& geometry,
const I3RecoPulseSeriesMap& pulsesMap,
const I3Particle& particle,
double trackCylinderRadius
);
Python bindings:
- icecube.common_variables.track_characteristics.calculate_track_characteristics((I3Geometry)geometry, (I3RecoPulseSeriesMap)pulses_map, (I3Particle)particle, (float)track_cylinder_radius) I3TrackCharacteristicsValues :
Calculates the track characteristics values, e.g. avg_dom_dist_q_tot_dom, empty_hits_track_length, track_hits_separation_length, and track_hits_distribution_smoothness, for the given I3Geometry, the given I3RecoPulseSeriesMap, and the given track, given through the I3Particle object, for pulses within the given cylinder radius around the given track.
Examples¶
This section should give some examples how to calculate the track characteristics for different use-cases.
Calculating the track characteristics within Python¶
To calculate the track characteristics for a given I3RecoPulseSeriesMap and a
given I3Particle using the calculate_track_characteristics()
utility
function within your Python script, you could do:
from icecube.icetray import I3Units
from icecube.common_variables import track_characteristics
geometry = frame['I3Geometry']
pulses_map = frame['my_I3RecoPulseSeriesMap']
particle = frame['my_I3Particle']
cylinder_radius = 150*I3Units.m
track_characteristics_values = track_characteristics.calculate_track_characteristics(
geometry,
pulses_map,
particle,
cylinder_radius
)
print "Calculation results: %s"%(track_characteristics_values)
A full script example can be found in the file
$I3_SRC/CommonVariables/resources/examples/track_characteristics/calculate_track_characteristics.py
.
Using the I3TrackCharacteristicsCalculatorSegment traysegment¶
Using the I3TrackCharacteristicsCalculatorSegment()
icetray traysegment to
calculate and to book track characteristics cut variables is the preferred and
easiest way of doing it. A full script example can be found in the file
$I3_SRC/CommonVariables/resources/examples/track_characteristics/I3TrackCharacteristicsCalculatorSegment.py
.
The following code snippet illustrates the core points:
...
from icecube.icetray import I3Units
from icecube import hdfwriter
from icecube.common_variables import track_characteristics
pulses_map_name = 'MaskedOfflinePulses'
reco_particle_name = 'MPEFit_SLC'
tableio_keys_to_book = []
tableio_keys_to_book +=\
tray.AddSegment(track_characteristics.I3TrackCharacteristicsCalculatorSegment, 'tc',
PulseSeriesMapName = pulses_map_name,
ParticleName = reco_particle_name,
OutputI3TrackCharacteristicsValuesName = reco_particle_name+'Characteristics',
TrackCylinderRadius = 150.*I3Units.m,
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).