AliPhysics  068200c (068200c)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
EMCal Correction Framework

EMCal Correction Framework

The new EMCal correction framework centralizes all of the analysis-level EMCal corrections into a single task: AliEmcalCorrectionTask. This task coordinates the running of a configurable list of individual "correction components", where a correction component means a single correction to be performed: cell-level energy calibration, or cluster-level non-linearity correction, or cluster-track matching, etc. The set of corrections to run, as well as their order and their configurable parameters, is set in a YAML configuration file. A default config file containing the centralized standard set of parameters is shared by all users, and each user additionally writes their own user config file, overwriting desired variables.

The motivation of this new approach is the following:

  • Centralize code so that there are not many similar versions of code used by different people
  • Provide a simple and unified interface to make life easier for both users and developers
  • Reduce likelihood of mistakes for users (make it obvious to a user if they are deviating from a recommended config, and avoid setting arguments through AddTask macros)

The following correction components are available:

  • CellBadChannel – Sets cells marked as bad to E = 0, using OADB bad channel map.
  • CellEnergy – Performs energy calibration of cells, using OADB calibration.
  • CellTimeCalib – Performs time calibration of cells, using OADB calibration.
  • Clusterizer – Clusterizes a collection of cells into a collection of clusters.
  • ClusterExotics – Flags exotic clusters for removal from the cluster collection.
  • ClusterNonLinearity – Corrects cluster energy for non-linear response.
  • ClusterTrackMatcher – Matches each track to a single cluster, if they are in close enough proximity.
  • ClusterHadronicCorrection – For clusters that have one or more matched tracks, reduces the cluster energy in order to avoid overestimating the particle's energy.
  • PHOSCorrection – Perform PHOS correction via an interface to the PHOS tender.

This new correction task unifies what was previously done by tasks such as:

...and other similar tasks.

Using the EMCal Corrections Framework

Below, follow the instructions to implement the new Correction Task in your analysis. Further down the page, you will find instructions on how to transition from the old correction method(s) to the new correction method, including how to configure the corrections, and how to test your analysis results in the new vs. old correction method. Testing your corrections configuration is an extremely important step, as failure to do so could lead to incorrect results!

Setup the Correction Task

There are two steps:

Switching to the EMCal Corrections Framework

For those who are switching to this framework, a special page has been prepared to explain the process. This page explains how to configure the correction framework alongside the previous set of corrections, allowing you to test and show that you get the same results with the new and old corrections! For the instructions, please see Switch to the EMCal Correction Framework.

Configure the Correction Add Task (or train wagon)

To enable the correction task, add the following lines to your run macro:

correctionTask->SelectCollisionCandidates(kPhysSel);
// Set the user configuration file, assuming that your file is called "userConfiguration.yaml" and is located in
// the current directory. This also supports alien:// paths!
correctionTask->SetUserConfigurationFilename("userConfiguration.yaml");
// Initialize the configuration and corrections in the correction task
// It is EXTREMELY important to run this function in your run macro!
correctionTask->Initialize();

LEGO Train Wagon

There are some special procedures for the LEGO train. There will be a centralized EMCal Correction Task wagon which contains standard settings such as physics selection, etc. Then the user will create a wagon which calls PWG/EMCAL/macros/ConfigureEmcalCorrectionTaskOnLEGOTrain(std::string suffix). This will return an EMCal Correction Task for you to configure with your particular YAML configuration file and then initialize.

To setup this wagon, use the macro listed above. One argument is required: the suffix. This suffix should be some unique identifier for your analysis - it could be your name, your analysis, whatever you like. The precise value only matters if you are using specialization - in such a case, your suffix for the configuration wagon must match the specialization suffix.

Then in the macro customization of your configuration wagon, you specify your YAML configuration file and initialize the configuration. It should looks something like the following:

// Set your user configuration
__R_ADDTASK__->SetUserConfigurationFilename("userConfiguration.yaml");
// It is extremely important to pass "true" to Initialize().
__R_ADDTASK__->Initialize(true);

Note that your configuration wagon should depend on the centralized correction task wagon, but your tasks (such as user tasks, user tasks, etc) should depend only on the centralized correction task wagon. They should not depend on your configuration wagon!

Configuring Corrections

The corrections configuration file is specified via a file written in the YAML markup language. YAML is quite readable and is commonly used for configuration files. Although it should be straightforward to read and write, more information on its use can be found through the examples available here. All** configuration and options are set through the YAML file, from setting the clusterizer type to the name of the tracks!

The configuration is determined by two files: the base default file (located in $ALICE_PHYSICS/PWG/EMCAL/config/), as well as the user configuration file. Any changes that you need to make should be done in the user configuration file! Note that any setting that you have in the user file will override the default file!

Introducing features of the configuration file

We will discuss a number of features including:

  • Setting cells, clusters, and tracks (input objects)
  • Comments
  • Enumerations
  • Advanced usage options

To discuss the configuration and introduce, consider the configuration excerpt below as an example:

# This is a comment! Comments can also be on inline - everything after the hash is a comment
inputObjects: # Define all of the input objects for the corretions
cells: # Configure cells
# The user can select the name of each container
# The names don't need to correspond to any particular scheme
defaultCells:
# Note that we support the "usedefault" pattern of setting branch names.
branchName: "usedefault"
clusterContainers: # Configure clusters
# The user can select the name of each container
# The names don't need to correspond to any particular scheme
defaultClusterContainer: # Name of a cluster input (corresponds to a cluster container)
# Sets the branch name
branchName: "usedefault"
# Takes all default cuts!
defaultClusterContainer_1: # Name of another cluster input which inherits from defaultClusterContainer
# The branch name is inherited from defaultClusterContainer!
minE: 0.0 # Cluster min E
minPt: 0.0 # Cluster min pt
defaultClusterContainer_2: # Name of another cluster input which inherits from defaultClusterContainer
# The branch name is inherited from defaultClusterContainer!
minE: 0.0 # Cluster min E
minPt: 0.0 # Cluster min pt
# Handled particularly for cluster containers
clusNonLinCorrEnergyCut: 0.15 # formerly "minPt" in the non-linearity AddTask()
trackContainers:
# The user can select the name of each container
# The names don't need to correspond to any particular scheme
defaultTrackContainer: # Name of a track input (corresponds to a track container)
# Sets the branch name
branchName: "usedefault"
# Takes all default cuts!
defaultTrackContainer_1: # Name of another track input which inherits from defaultTrackContainer
# The branch name is inherited from defaultClusterContainer!
minPt: 0.15 # Track min pt
trackFilterType: kHybridTracks # Set the track filter type. Check the documentation for possible values
#aodFilterBits: # Can also set AOD filter bits. Check the docuemntation for more information
# - 16
# - 1
sharedParameters:
# You can define here any parameters that you would like to share between tasks. See the documentation for more information
# This next section defines the settings for the "AliEmcalCorrectionCellEnergy" correction.
# Note how the "AliEmcalCorrection" part of the name is not required when defining the settings
CellEnergy:
# All tasks can be enabled or disabled by setting the "enabled" property.
enabled: true
# Most tasks can create histograms, which are useful for QA or comparison with other corrections.
createHistos: true
# This defines the settings for the "AliEmcalCorrectionCellBadChannel" correction.
CellBadChannel:
enabled: true
createHistos: true
# This defines the settings for the "AliEmcalCorrectionCellTimeCalibration" correction.
CellTimeCalib:
enabled: true
createHistos: true
# This defines the settings for the "AliEmcalCorrectionClusterizer" correction.
Clusterizer:
enabled: true
createHistos: true
# Sets the cluster branch name for this particular task.
clusterBranchName: "sharedParameters:clusterBranchName"
# Sets the Clusterizer type based on the same familiar enumeration.
# Note that you should _not_ include the prefix as you usually would for setting an enumeration. Only list the value.
clusterizer: kClusterizerv2
cellE: 0.05
seedE: 0.1
cellTimeMin: -1 # Min cell time (s)
cellTimeMax: +1 # Max cell time (s)
clusterTimeLength: 1 # Maximum time difference between the digits inside EMC cluster (s)
w0: 4.5

Setting cells, clusters, and tracks (input objects)

To properly configured the Correction Tasks, we need to indicate which cells, clusters, and tracks are needed (collectively referred to as input objects). These are configured in the inputObjects section. Within this section, we configure cells for input cells, clusterContainers for input cluster containers, and trackContainers for input tracks. Note that each subsection can contain multiple objects.

Each input object follows the same pattern:

objectName: # Used to refer to this object in the YMAL configuration
branchName: "usedefault" # The name of the branch that we want. The "usedefualt" pattern is supported here
option: value # We support a wide variety of options, listed below.

Although it is not required for your task to use EMCal containers, they are used internally in the Correction Task, so it is important to understand a bit about how they work. In particular, any filtering of the collections (such as AOD Track Filtering) is applied for the corrections, but the filtering does not remove anything from the collections! In addition, we always write cell/cluster/track corrections in place - it is generally not possible to write out new collections. Thus, it is then the users' responsibility to filter the collection using the information available! One particularly easy way to do so is to use EMCal containers, but it is not required! In the case that the user wants to manually filter, for example, tracks before running the Correction Framework, one can run AOD Track Filtering and then select no additional track filtering using kNoTrackFilter.

The available configuration options are listed below. Direct configuration through the YAML file is limited to a subset of all available configuration options. If you require additional options, please contact the developers - such additions are usually trivial. Alternatively, after calling Initialize(), all containers are available for configuration as usual, so any additional options can be set by hand until implemented by the developers.

Cells:

Property Value
branchName String selecting the branch name
embedding True if the cells branch should be taken from an embedded (external) event

EMCal Containers:

Property Value
Container name This is set by the object name in the YAML config
branchName String selecting the branch name
embedding True if the branch should be taken from an embedded (external) event
minPt Double setting the minimum pT of the container
minE Double setting the minimum energy of the container
(minEta, maxEta) A pair of doubles to set the min and max eta of the container. Note that they must be set as a pair!
(minPhi, maxPhi) A pair of doubles to set the min and max phi of the container. Note that they must be set as a pair!

Clusters (Includes all options for EMCal Containers):

Property Value
clusNonLinCorrEnergyCut Double determining the cluster non-linearity energy cut
clusHadCorrEnergyCut Double determining the cluster hadronic cluster energy cut
includePHOS True if PHOS cluster should be included

Tracks (Includes all options for EMCal Containers):

Property Value
trackFilterType Enumerated value determining the track filtering to apply to the container. The enumerations are defined in AliEmcalTrackSelection and include: kNoTrackFilter, kCustomTrackFilter, kHybridTracks, kTPCOnlyTracks
aodFilterBits Sets values based on the evaluated bits (ie to set bit 3, pass 2^3 = 8). To set it properly, see below. To use aodFilterBits, Be sure to set the trackFilterType to kCustomTrackFilter!
trackCutsPeriod Sets the track cuts period for the track container. A default can also be set for all track containers using static methods of AliTrackContainer independent of the correction task. See AliTrackContainer for more information

The aodFilterBits are set as an array. This is possible to express in two ways in YAML:

aodFilterBits: [1, 256]
# Alternatively
aodFilterBits:
- 1
- 256

Comments

Comments include anything after a hash ("#"). Of course, they are not required, but are highly recommended! You can add a comment on the same line as where you define a property - just add the "#" after you are done defining the property.

Enumerations

Enumerations are supported as expected. Just set the value as you normally would. However, be sure that you don't include class where it is defined!

Example configuration and further information

For a survey of the available configuration options and information about the meaning of each, see the default configuration file located in $ALICE_PHYSICS/PWG/EMCAL/config/. This also serves as an example configuration, Note that once the Correction Task is initialized using the Initialize() function, all corrections are configured and created. Consequently, any additional configuration can be done manually if desired. However, this approach is strongly discouraged. Instead, it is better to change the YAML configuration file so that there is a record of settings.

Advanced usage options

There are a number of useful advanced options to make the Corrections Framework simpler and more pleasant to use. These options are described below.

Shared parameters

Often, a user will want to change some parameters in unison. Say, if a pt cut is changed, it should be changed everywhere. In such a case, it is useful to able to define a variable so that one change will change things everything. This can be accomplished by defining a parameters in the "shared parameters" section of the YAML file. The name of the parameter defined in the shared parameters section can be referenced in other areas of the file by prepending sharedParameters: to the parameter name. Consider the example below:

sharedParameters:
aMinimumValue: 3
Correction1:
exampleValue: "sharedParameters:aMinimumValue"
...
Correction2:
anotherExample: "sharedParameters:aMinimumValue"

In the example, any change to aMinimumValue will be propagated to exampleValue in Correction1 and anotherExample in Correction2. Note that the parameter name (here, aMinimumValu) can be anything that the user desires. When setting the value, don't forget to prepend "sharedParameters:" (in our example, "sharedParameters:aMinimumValu")!