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:

\[AvgDomDistQTotDom := \frac{1}{\sum_{i=1}^{NHitDoms} QTotDom_i} \sum_{i=1}^{NHitDoms} dist(Dom_i,Track) \cdot QTotDom_i\]

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.

\[domDistList := \left\{ distAlongTrack(Dom_i, Track) \right\}\]

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:

\[ascDomDistList := ascendingSort(domDistList)\]

The EmptyHitsTrackLength variable is then simply the maximal difference of successive distance elements of the sorted distance list:

\[EmptyHitsTrackLength := max( ascDomDistList[i+1] - ascDomDistList[i] )\]

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:

\[TrackHitsDistributionSmoothness := \frac{j}{n} - \frac{l_j}{l_n}\]

with $j$ being the pulse with:

\[max( \left| \frac{j}{n} - \frac{l_j}{l_n} \right| )\]

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

Track Characteristics¶

Variable Definitions¶

AvgDomDistQTotDom¶

EmptyHitsTrackLength¶

TrackHitsDistributionSmoothness¶

TrackHitsSeparationLength¶

The I3TrackCharacteristicsCalculator icetray module¶

Available traysegments¶

Utility functions¶

Utility function `CalculateTrackCharacteristics`¶

Examples¶

Calculating the track characteristics within Python¶

Using the I3TrackCharacteristicsCalculatorSegment traysegment¶

Table of Contents

Previous topic

Next topic

This Page

Track Characteristics¶

Variable Definitions¶

AvgDomDistQTotDom¶

EmptyHitsTrackLength¶

TrackHitsDistributionSmoothness¶

TrackHitsSeparationLength¶

The I3TrackCharacteristicsCalculator icetray module¶

Available traysegments¶

Utility functions¶

Utility function CalculateTrackCharacteristics¶

Examples¶

Calculating the track characteristics within Python¶

Using the I3TrackCharacteristicsCalculatorSegment traysegment¶

Utility function `CalculateTrackCharacteristics`¶