[PWGCF/FemtoUniverse] Efficiency correction in 3D

[davkk]

Changes summary:

• Fix in femtoUniverseProducerTask.cxx
  • the producer should now correctly classify MC particles coming from material
• EfficiencyCorrection class update
  • create a custom histogram registry only for efficiency correction
  • fill 3D histograms for MC truth & MC reco, with fillTruthHist and fillRecoHist methods
  • add configurable variables (via confEffCorVariables), based on which histograms are loaded from CCDB
• New macro for efficiency & weights calculation
  • calculates the efficiency and weights, from 3D histograms generated by EfficiencyCorrection class

Complete workflow guide

1. Add the FemtoUniverseEfficiencyCorrection class to your task.

First, add it as a top-level field to the task struct:

struct FemtoUniversePairTaskTrackTrackExtended {
    // ...
    EffCorConfigurableGroup effCorConfGroup;
    EfficiencyCorrection effCorrection{&effCorConfGroup};
    // ...
}

Here, EffCorConfigurableGroup acts as a container with all the necessary configurable variables, which get added to the task's configuration.

2. Initialize the class in the init() method of your task.

As the first parameter, pass a reference to the registry you want the histograms to live. Then, pass a list of AxisSpecs, always in order of: $p_T$, $\eta$, multiplicity/centrality.

void init(InitContext&) {
    // ...
    effCorrection.init(
        &effCorrRegistry,
        { // this is an exemplary binning, based on available configurables
            static_cast<framework::AxisSpec>(confTempFitVarpTBins), // binning for pT
            {confEtaBins, -2, 2}, // binning for eta
            confMultBins, // binning for multiplicity/centrality
        }
    );
    // ...
}

3. Add filling of the histograms to your task.

// fill reco histograms with:
effCorrection.fillRecoHist<ParticleNo::ONE>(particle, pdgCodeOne);
if (!isSame) {
    effCorrection.fillRecoHist<ParticleNo::TWO>(particle, pdgCodeTwo);
}

// fill truth histograms with:
effCorrection.fillTruthHist<ParticleNo::ONE>(particle);
if (!isSame) {
    effCorrection.fillTruthHist<ParticleNo::TWO>(particle);
}

4. Add weights to your histograms.

// get weight for the given particle from loaded histograms
float weight = effCorrection.getWeight(ParticleNo::ONE, particleOne);
if (!confIsSame) {
  weight *= effCorrection.getWeight(ParticleNo::TWO, particleTwo);
}

You can then use that weight, by passing it to fill method of the histogram

5. Run the task.

In the results file, the histograms will be stored under the EfficiencyCorrection directory.

6. Run the calculateEfficiencyCorrection.cxx macro.

The easiest way to run the macro is to first compile it. Compiled macro comes with helpful CLI flags:

  -f <path to results ROOT file>
  -d <path to directory within file>
  -p <projection> [optional, default: no projection, 3D histogram]
    Available projections:
      x - projection onto pT axis (1D histogram)
      yx - projection onto pT, eta (2D histogram)
      zx - projection onto pT, centrality/multiplicity (2D histogram)

Exemplary usage:

# compile the macro with:
g++ `root-config --libs --glibs --cflags` \
    --std=c++20 \
    -O3 \
    /path/to/calculateEfficiencyCorrection.cxx

# run the macro with:
./a.out \
    -f /path/to/results.root \
    -d task-name/EfficiencyCorrection/one

# or with projection (in this case, pT vs. eta):
./a.out \
    -f /path/to/results.root \
    -d task-name/EfficiencyCorrection/two \
    -p yx

Remember to enable histogram filling in the configuration:

"confEffCorFillHist": "true",

7. Upload to CCDB

To upload the resulting weights to CCDB, you can use o2-ccdb-upload tool, available in the O2 environment.

# for example:
o2-ccdb-upload \
    --host http://alice-ccdb.cern.ch \
    --path Users/d/dkarpins/Correction \ # change to your path!
    --file efficiency-correction.root \
    --key hWeights

In this case, to view the uploaded object, you can navigate to: http://alice-ccdb.cern.ch/browse/Users/d/dkarpins/Correction.

8. Apply the corrections in the analysis.

Once the ROOT object is uploaded, you can use it in your task. To do so, add its timestamp to confEffCorCCDBTimestamps ("Valid from" column).

Exemplary configuration for applying the correction:

"confEffCorApply": "true",
"confEffCorFillHist": "false",
"confEffCorVariables": "pt,eta", // adjust based on which projection you have uploaded
"confEffCorCCDBUrl": "http://alice-ccdb.cern.ch",
"confEffCorCCDBPath": "Users/d/dkarpins/Correction", // change to your path
"confEffCorCCDBTimestamps": {
    "values": [
        "1747760963753", // timestamp for particle one
        "1747760972019" // timestamp for particle two, if needed
    ]
},

[github-actions]

O2 linter results: ❌ 48 errors, ⚠️ 0 warnings, 🔕 1 disabled