AliPhysics  ea71c62 (ea71c62)
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Jet finding framework

Jet Framework Users

For users more familiar with the framework, see the Jet Framework Topics section below.

For those who are less familiar, please see the introduction below.

Introduction to the Jet Framework

Framework Philosophy

The philosophy of the Jet Framework is to provide access to common objects and functions, thereby allowing the user to focus on the particulars of their task, as well as reducing duplicate boilerplate code from user tasks, helping to reduce the inevitable bugs introduced by many copies. To achieve these goals, the Jet Framework uses the EMCal Framework defined in $ALICE_PHYSICS/PWG/EMCAL/.

The EMCal framework extends the standard ALICE Analysis Framework, AliAnalysisTaskSE to provide commonly used objects, such as access to clusters and tracks. In the standard framework, the user is responsible for tasks such as loading the event properly. With the EMCal framework, such tasks are already taken care of for the user, along with providing basic QA histograms and other variables to simplify tasks.

The Jet Framework extends this concept, introducing support for collections of jets in AliAnalysisTaskEmcalJet. Note that despite the name including EMCal, the framework works equally well for both charged and full (charged + neutral) jets!

The EMCAL framework base class is AliAnalysisTaskEmcal. It contains the cluster and track collections that are used by the containers. The Jet framework base class is AliAnalysisTaskEmcalJet and it provides the objects for jet containers. Since these are used across multiple PWGs, they are located in the EMCAL and JETFW folders, respectively, in $ALICE_PHYSICS/PWG.

To use the Jet Framework, the user implements an analysis task, usually named AliAnalysisTaskEmcalJet{AnalysisName}, which includes a main implementation file (.cxx) and a header file (.h). In addition, the user implements a macro to call their analysis task with the proper options, usually named AddTaskEmcalJet{AnalysisName}. Lastly, the user must have a way to call the macro - this is usually done either via a run macro (which could be used to submit to the grid), or via a wagon on a LEGO train. Frequently, the analysis task is placed in $ALICE_PHYSICS/PWGJE/EMCALJetTasks/UserTasks/ or $ALICE_PHYSICS/PWGJE/FlavourJetTasks/, while the run macros is placed in $ALICE_PHYSICS/PWGJE/EMCALJetTasks/macros/ or $ALICE_PHYSICS/PWGJE/FlavourJetTasks/macros/, respectively.

Containers

Containers are a central concept in the EMCal framework. To conduct an analysis, a user needs access to objects such as clusters, tracks, or jets. Containers are wrappers around these collections, allowing a consistent interface regardless of the underlying object. Furthermore, the containers help apply and manage cuts and selections.

To learn about containers, including a usage example, looking the EMCal framework page on containers, available here.

For more information on the containers, see the base class, AliEmcalContainer, as well as the particular containers, AliClusterContainer, AliParticleContainer, AliTrackContainer, AliMCParticleContainer, and AliJetContainer.

Jet Finding

Since Jet Finding is such an integral part of the framework, it is taken care of with an straightforward and simple interface. To perform jet finding, the user specifies the tracks and clusters, as well as the algorithm, R parameter, jet type (charged or full), and a few additional options. These options are passed to AddTaskEmcalJet, and it performs all necessary actions for the user, including loading the jets into the jet container and making them available to the user. This means that adding one task to a run macro can take care of most basic jet finding needs.

While basic jet finding is straightforward, this does not preclude additional tasks. For example, using another macro (AddTaskRhoNew), the average background can be calculated. The actual implementation of background subtraction is performed via another class, with information available here. In general, the user will utilize various tasks that depend on functionality implemented in fastjet (via AliFJWrapper). However, a user will rarely, if ever, need to modify the wrapper! (Only in the case of adding new functionality).

For further information on jet finding, see AliEmcalJetTask. For further information on background calculation, see AliAnalysisTaskRho. In general, further jet documentation can be viewed at the ALICE FJ Utilities Wrapper documentation. For more advanced jet finding details and features, see the interface to fastjet, AliFJWrapper.

Analysis Chain

Using the philosophy, each user can create their own analysis task, and then run it either using a Run Macro (locally to test, and then on the grid), or create a wagon to run it on the LEGO train.

Your Analysis Task

Inherit from AliAnalysisTaskEmcalJet for jet focused analyses. If jet features are not required, one may instead inherit from AliAnalysisTaskEmcal.

Both of the base classes inherit from AliAnalysisTaskSE, but additional functionality is implemented (such as automatic loading of data into containers for each event), so the user functions change slightly. Instead of implementing UserExec(), the user should implement Run() and FillHistograms().

For more information, look at the base classes, AliAnalysisTaskEmcal and AliAnalysisTaskEmcalJet, as well as the sample task, AliAnalysisTaskEmcalJetSample.

Your Add Task

The AddTask is used to setup your analysis task, allowing it to run. This code is interpreted through CINT (ie through ROOT), so it is best to avoid complicated code, as debugging can be rather difficult.

Often, the AddTask is used to set properties such as the tracks or clusters. To handle this in a flexible manner, it is recommended to utilize the "usedefault" approach as demonstrated in many AddTask macros, such as AddTaskEmcalJet. Doing so ensures that the proper collection of objects is loaded regardless of the type of file that is used. Alternatively, the containers can be setup in your run macro or wagon. To see the most up to date names for these collections, see AddTaskEmcalJetSample.

For examples, see AddTaskEmcalJetSample and AddTaskEmcalJet.

Running Your task

Once your have created your task, the next step is to run it. There are a few different options:

  • Attaching a wagon to the LEGO train. For more information, see the LEGO Trains (requires a grid certificate) and the LEGO Train TWiki Page.
  • Run via a Run Macro. For an example, see runEMCalJetSampleTask.C. It runs the primary tasks necessary for running an analysis, so simple modification of it should be sufficient to get started. To try running it, runEMCalJetSampleTask.sh provides a slightly more use friendly interface.

    A Run Macro enables two modes of operation:

    • Run locally to test code
    • Submit to the grid

    NOTE: Since you will need to modify the run macro, it is highly recommended to copy the run macro to another location or to make a new branch for it!

Regardless of method, there are a number of considerations to take into account. A few are listed below.

Physics Selection

When running your task, it is necessary to specify the physics data that you are interested in analyzing. This should be specified using SelectCollisionCandidate() in your run macro. The function is defined in AliAnalysisTaskSE.

Note that you only need a physics selection task when using ESDs. In that case, as per Salvatore's email on Feb 18, 2016, use the physics selection task located at OADB/macros/AddTaskPhysicsSelection.C for the old centraltiy framework, or OADB/COMMON/MULTIPLICITY/macros/AddTaskMultSelection.C for the new centrality framework.

For more information, see AliAnalysisTaskSE and the possible selections in AliVEvent. For an example of an implementation, see runEMCalJetAnalysisNew.C.

Necessary Tasks

There are a number of tasks which are required to run before running your analysis in the proper order. These tasks include the EMCal corrections (cell corrections, cluster corrections, hadronic corrections - see here) and jet finding. For an up to date task, see runEMCalJetAnalysisNew.C.

Additional notes

A lot of event properties are also automatically available when you derive from AliAnalysisTaskEmcal. For example, the centrality percentile of the current event is available in fCent, and the bin as fCentBin (see the source for the precise binning options). Note that if you are using the new centrality framework (OADB/COMMON/MULTIPLICITY/macros/AddTaskMultSelection.C), you need to set task->SetUseNewCentralityEstimation(kTRUE)

Other additional features include:

  • Calculating \(\Delta\phi\) in any range using DeltaPhi(elementOne, elementTwo, minRange, maxRange).
  • Calculating \(\Delta\eta,\Delta\phi\) for a track and cluster.
  • Generating a fixed bin array.

In general, it is extremely helpful to be familiar with the base classes. It can save you a tremendous amount of work!


Jet Framework Topics

Basic jet finding

Basic jet finding is provided by the AliEmcalJetTask class which is found in the library libPWGJEEMCALJetTasks (source code in PWGJE/EMCALJetTasks). An add task macro is provided in PWGJE/EMCALJetTasks/AddTaskEmcalJet.C:

AliEmcalJetTask* AddTaskEmcalJet(
const char *nTracks = "usedefault",
const char *nClusters = "usedefault",
const Double_t radius = 0.4,
const Int_t type = AliJetContainer::kFullJet,
const Double_t minTrPt = 0.15,
const Double_t minClPt = 0.30,
const Double_t ghostArea = 0.005,
const Int_t recombScheme = AliJetContainer::pt_scheme,
const char *tag = "Jet",
const Double_t minJetPt = 0.,
const Bool_t lockTask = kTRUE,
const Bool_t bFillGhosts = kFALSE
)

Charged jets

For charged jets, running the AliEmcalJetTask is sufficient. The track selection is described here.

Full jets

EMCal/DCal cluster corrections have to be applied beforehand as explained here.

EMCal/DCal cluster objects contain different fields to accomodate different "levels" of corrections to the energy deposition. The user must be careful in selecting the level of corrections required for his/her analysis. The various corrected energies are selected via

pFuJetTask->GetClusterContainer(0)->SetDefaultClusterEnergy(energyType);

where pFuJetTask is the pointer to the AliEmcalJetTask object and energyType is an integer number. It can be either -1 (no additional corrections to the cluster energy) or one of the enum constants defined in AliVCluster:

enum VCluUserDefEnergy_t {
kNonLinCorr = 0,
kHadCorr = 1,
kUserDefEnergy1 = 2,
kUserDefEnergy2 = 3,
kLastUserDefEnergy = 4
};

Particle level jets (MC)

For particle level jets it is usually enough to filter primary particles (see Track selection).

Utilities (e.g. FJ contribs)

For information on utilities such as fastjet contrib, see Jet Framework Utilities.

Embedding

Embedding here means to combine two events at the level of reconstructed tracks and EMCal cells or random tracks or clusters.

Currently the embedding framework uses an older version of the framework that requires manual filtering of the tracks as explained in find doc and add here link.

See Embedding for more information on the embedding classes.

Jet tagger

The task AliAnalysisTaskEmcalJetTagger allows to tag a jets as "close" and/or sharing a minimun fraction of constituent pT. This is useful for:

  1. Matching PYTHIA jet before and after embedding
  2. Match jets with "signal" jets. A signal jet can be defined e.g. as a jet with a minimum cut pT > 4 GeV/c on the constituents

See Jet Tagging for more details.

Unfolding

Unfolding

User tasks

User tasks using the EMCal jet framework

Appendix

For clarifications, corrections or improvements, please contact Chiara Bianchin and Raymond Ehlers.