CommonVariables

This project is maintained by Martin Wolf <martin.wolf@fysik.su.se>.

The CommonVariables project provides a collection of C++ utility functions (with python-bindings), icetray modules, tableio converters, and icetray traysegments for common IceCube cut variables.

The project has been started with the intension to have a better, more ordered and more flexible implementation of the I3Cuts code, which is currently part of the phys-services project.

Having one (code reviewed) project for common cut variables, which will be used by the entire collaboration will speedup physics analyses and will ensure that everyone uses the same (correct) code for the same cut variables.

Since each utility function is implemented in C++ and has python bindings, the cut variables calculation codes can be used in both, C++ and Python, user programs. (See also The project’s structure section below.)

For a list of currently supported common IceCube cut variables, see the documentation of the individual sub-projects of CommonVariables:

Dependencies

The CommonVariables project depends on the following IceCube projects:

  • icetray (>= V12-08-00)

  • dataclasses (>= V12-08-00)

  • phys-services (>= V12-08-00)

    Uses the utility functions contained inside the I3Calculator:: namespace.

  • tableio (>= V12-08-00)

    For tableio converters, which book the calculation results into a data output file, e.g. a ROOT file or a HDF file.

The project’s structure

The CommonVariables project is divided into several sub projects. Each sub project is responsible for calculating and booking one or a set of related-to-each-other common IceCube cut variable(s). One of these sub projects is for instance “direct_hits” for calculating direct hits.

From the C++ point of view

In C++ the entire project is contained in the namespace common_variables::. Each sub project has its own namespace inside the common_variables namespace. For instance the direct hits sub project has the namespace direct_hits:: and direct hits utility functions can be accessed by prefixing the namespace common_variables::direct_hits:: to those functions.

From the Python point of view

Each C++ utility function has python-bindings, so it can be accessed also from within a Python script. In Python the common_variables project is structured in the same way as it is from the C++ point of view. It has a main python module named common_variables and each sub project has its own python sub module within this python main module. For instance utility functions of the direct hits sub project can be accessed through the python module icecube.common_variables.direct_hits.

Utility functions, classes, icetray modules, tableio converters, and traysegments of a particular sub project are all contained inside that particular python sub module. For instance the icetray module I3DirectHitsCalculator that calculates direct hits can be accessed in Python through icecube.common_variables.direct_hits.I3DirectHitsCalculator.

Given the information above, one can draw the following Python module structure diagram for the direct_hits sub project:

common_variables
    .direct_hits
        .I3DirectHitsCalculator (an icetray module)
        .I3DirectHitsCalculatorSegment (an icetray traysegment)
        .I3DirectHitsValues (an I3FrameObject)
        .I3DirectHitsValuesConverter (a tableio converter)
        .I3DirectHitsDefinition (a simple class)
        .I3DirectHitsTimeWindow (a simple class)

Important Python Import note for CommonVariables

CommonVariables can contain optional sub-projects, which will only get compiled, when all of the IceCube software projects, on which they depend on, are available in the particular meta-project. This “optional-sub-project” feature allows the usage of CommonVariables within a very light IceCube meta-project, like “offline-software”.

In order to avoid run-time errors of your Python script, when importing the python module of an optional sub-project, you should always import the CommonVariables sub-project’s python module explicitly at the beginning of your Python script:

from icecube.common_variables import direct_hits

Optional sub-project will not be loaded automatically, when you import the main Python module of CommonVariables by typing: from icecube import common_variables! They need to get imported explicitly: from icecube.common_variables import direct_hits. The good thing is, when you do the sub-project import right at the beginning of your script, the script will fail (with some usefull instructions) immediately after it had been started, instead of somewhere in the middle of your script, if dependencies cannot be fulfilled.

So you do not need to know what sub-projects are static, and what sub-projects are optional, if you do the sub-project’s import always explicitly.

The old and the new variable names

CommonVariables renames almost all existing variables with names, which are (hopefully) more descriptive than before. The following table gives an overview on the old and the new variable names, and in which CommonVariables sub-project they can be found.

Old name

CV sub-project

CV name

n_dir

direct_hits

n_dir_doms

l_dir

direct_hits

dir_track_length

s_dir

direct_hits

dir_track_hit_distribution_smoothness

n_chan

hit_multiplicity

n_hit_doms

q_tot

hit_statistics

q_tot_pulses

s_all

track_characteristics

track_hits_distribution_smoothness

LEmpty

track_characteristics

empty_hits_track_length

Separation

track_characteristics

track_hits_separation_length

Variable definition changes

Over time it could be possible, that variables change their definitions. The lists below lists these changes in order to keep track of them to explain possible differences of their distributions between different used versions of CommonVariables.

  • track_hits_separation_length (of track_characteristics, rev. no. of change: 97739 (2013-01-21))

    To determine the COG of the first and last quartile of the hits, it does not take the individual pulses anymore. Instead it takes the time of the first pulse of a DOM and the integrated charge of the DOM to determine the quartiles.

    This change was necessary because of wavedeform, which fits pulses to a waveform. So an individual pulse cannot be regarded as an individual photo- electron. Without that change, track_hits_separation_length could behave differently for data and MC.

How to inspect a sub project with icetray-inspect

If you want to know what kind of things are included in a sub project using the icetray-inspect program, you can do so, for instance for the direct_hits sub project, by typing:

icetray-inspect common_variables.direct_hits

into your shell.

Project Manual