[Common] added reference run number to ReferenceComparator plots (#2569)

The number of the reference run is reported both in the title of the
ratio plot, and in a legend at the top of the superimposed histograms.

Author: aferrero2707

Modules/Common/etc/reference-comparator-example.json

@@ -47,6 +47,7 @@
             "outputPath": "Tracks/WithCuts",
             "normalizeReference": "true",
             "drawRatioOnly": "false",
+            "legendHeight": "0.2",
             "drawOption1D": "E",
             "drawOption2D": "COL",
             "inputObjects": [
@@ -78,6 +79,7 @@
             "default": {      
               "moduleName" : "QualityControl",
               "comparatorName" : "o2::quality_control_modules::common::ObjectComparatorChi2",
+              "ratioPlotRange" : "0.5",
               "threshold" : "0.5"
             }
           }

Modules/Common/include/Common/ReferenceComparatorPlot.h

@@ -37,7 +37,14 @@ class ReferenceComparatorPlot
   /// \param drawRatioOnly if true only  the ratio between current and reference plot is draw, otherwise also the individual plots are drawn in addition
   /// \param drawOption1D ROOT draw option to be used for 1-D plots
   /// \param drawOption2D ROOT draw option to be used for 2-D plots
-  ReferenceComparatorPlot(TH1* referenceHistogram, const std::string& outputPath, bool scaleReference, bool drawRatioOnly, const std::string& drawOption1D, const std::string& drawOption2D);
+  ReferenceComparatorPlot(TH1* referenceHistogram,
+                          int referenceRun,
+                          const std::string& outputPath,
+                          bool scaleReference,
+                          bool drawRatioOnly,
+                          double legendHeight,
+                          const std::string& drawOption1D,
+                          const std::string& drawOption2D);
   virtual ~ReferenceComparatorPlot() = default;
 
   TObject* getMainCanvas();

Modules/Common/include/Common/ReferenceComparatorTaskConfig.h

@@ -44,6 +44,8 @@ struct ReferenceComparatorTaskConfig : quality_control::postprocessing::PostProc
     bool normalizeReference{ false };
     // wether to only draw the current/reference ratio, or the inidividual histograms as well
     bool drawRatioOnly{ false };
+    // space reserved for the legend above the histograms, in fractions of the pad height
+    double legendHeight{ 0.2 };
     // ROOT option to be used for drawing 1-D plots ("HIST" by default)
     std::string drawOption1D{ "HIST" };
     // ROOT option to be used for drawing 2-D plots ("COLZ" by default)

Modules/Common/src/ReferenceComparatorPlot.cxx

@@ -26,6 +26,7 @@
 #include <TH2.h>
 #include <TCanvas.h>
 #include <TPaveText.h>
+#include <TLegend.h>
 
 namespace o2::quality_control_modules::common
 {
@@ -192,8 +193,14 @@ template <class HIST>
 class ReferenceComparatorPlotImpl1D : public ReferenceComparatorPlotImpl
 {
  public:
-  ReferenceComparatorPlotImpl1D(TH1* referenceHistogram, const std::string& outputPath, bool scaleReference, bool drawRatioOnly, const std::string& drawOption)
-    : ReferenceComparatorPlotImpl(scaleReference)
+  ReferenceComparatorPlotImpl1D(TH1* referenceHistogram,
+                                int referenceRun,
+                                const std::string& outputPath,
+                                bool scaleReference,
+                                bool drawRatioOnly,
+                                double legendHeight,
+                                const std::string& drawOption)
+    : ReferenceComparatorPlotImpl(scaleReference), mLegendHeight(legendHeight)
   {
     float labelSize = 0.04;
 
@@ -268,11 +275,21 @@ class ReferenceComparatorPlotImpl1D : public ReferenceComparatorPlotImpl
     mReferencePlot->SetOption((drawOption + "SAME").c_str());
     mReferencePlot->Draw((drawOption + "SAME").c_str());
 
+    if (!drawRatioOnly && mLegendHeight > 0) {
+      mHistogramLegend = std::make_shared<TLegend>(0.2, 0.91, 0.8, 0.98);
+      mHistogramLegend->SetNColumns(2);
+      mHistogramLegend->SetBorderSize(0);
+      mHistogramLegend->SetFillStyle(0);
+      mHistogramLegend->AddEntry(mPlot.get(), "current run", "l");
+      mHistogramLegend->AddEntry(mReferencePlot.get(), TString::Format("reference run %d", referenceRun), "l");
+      mHistogramLegend->Draw();
+    }
+
     // histogram with current/reference ratio
     mPadHistRatio->cd();
     mRatioPlot = createHisto1D<HIST>((canvasName + "_hist_ratio").c_str(), "", referenceHistogram);
     if (drawRatioOnly) {
-      mRatioPlot->SetTitle(referenceHistogram->GetTitle());
+      mRatioPlot->SetTitle(TString::Format("%s (ref. %d)", referenceHistogram->GetTitle(), referenceRun));
       mRatioPlot->GetXaxis()->SetTitle(referenceHistogram->GetXaxis()->GetTitle());
       mRatioPlot->GetYaxis()->SetTitle("current / reference");
     } else {
@@ -316,7 +333,7 @@ class ReferenceComparatorPlotImpl1D : public ReferenceComparatorPlotImpl
       mHistogramTitle->SetFillStyle(0);
       mHistogramTitle->SetTextAlign(22);
       mHistogramTitle->SetTextFont(42);
-      mHistogramTitle->AddText(referenceHistogram->GetTitle());
+      mHistogramTitle->AddText(TString::Format("%s (ref. %d)", referenceHistogram->GetTitle(), referenceRun));
       mHistogramTitle->Draw();
     }
   }
@@ -334,6 +351,11 @@ class ReferenceComparatorPlotImpl1D : public ReferenceComparatorPlotImpl
 
     copyAndScaleHistograms(hist, referenceHistogram, mPlot.get(), mReferencePlot.get(), getScaleReference());
 
+    double max = std::max(mPlot->GetMaximum(), mReferencePlot->GetMaximum());
+    double histMax = (mLegendHeight > 0) ? (1.0 + mLegendHeight) * max : 1.05 * max;
+    mPlot->SetMaximum(histMax);
+    mReferencePlot->SetMaximum(histMax);
+
     mRatioPlot->Reset();
     mRatioPlot->Add(mPlot.get());
     mRatioPlot->Divide(mReferencePlot.get());
@@ -353,13 +375,20 @@ class ReferenceComparatorPlotImpl1D : public ReferenceComparatorPlotImpl
   std::shared_ptr<TLine> mBorderRight;
   std::shared_ptr<TPaveText> mQualityLabel;
   std::shared_ptr<TPaveText> mHistogramTitle;
+  std::shared_ptr<TLegend> mHistogramLegend;
+  double mLegendHeight;
 };
 
 template <class HIST>
 class ReferenceComparatorPlotImpl2D : public ReferenceComparatorPlotImpl
 {
  public:
-  ReferenceComparatorPlotImpl2D(TH1* referenceHistogram, const std::string& outputPath, bool scaleReference, bool drawRatioOnly, const std::string& drawOption)
+  ReferenceComparatorPlotImpl2D(TH1* referenceHistogram,
+                                int referenceRun,
+                                const std::string& outputPath,
+                                bool scaleReference,
+                                bool drawRatioOnly,
+                                const std::string& drawOption)
     : ReferenceComparatorPlotImpl(scaleReference)
   {
     if (!referenceHistogram) {
@@ -427,7 +456,7 @@ class ReferenceComparatorPlotImpl2D : public ReferenceComparatorPlotImpl
     // histogram from the reference run
     mPadHistRef->cd();
     mReferencePlot = createHisto2D<HIST>((canvasName + "_hist_ref").c_str(),
-                                         TString::Format("%s (reference)", referenceHistogram->GetTitle()),
+                                         TString::Format("%s (ref. %d)", referenceHistogram->GetTitle(), referenceRun),
                                          referenceHistogram);
     mReferencePlot->GetXaxis()->SetTitle(referenceHistogram->GetXaxis()->GetTitle());
     mReferencePlot->GetYaxis()->SetTitle(referenceHistogram->GetYaxis()->GetTitle());
@@ -438,7 +467,7 @@ class ReferenceComparatorPlotImpl2D : public ReferenceComparatorPlotImpl
     // histogram with current/reference ratio
     mPadHistRatio->cd();
     mRatioPlot = createHisto2D<HIST>((canvasName + "_hist_ratio").c_str(),
-                                     TString::Format("%s (ratio)", referenceHistogram->GetTitle()),
+                                     TString::Format("%s (ratio wrt %d)", referenceHistogram->GetTitle(), referenceRun),
                                      referenceHistogram);
     mRatioPlot->GetXaxis()->SetTitle(referenceHistogram->GetXaxis()->GetTitle());
     mRatioPlot->GetYaxis()->SetTitle(referenceHistogram->GetYaxis()->GetTitle());
@@ -495,26 +524,33 @@ class ReferenceComparatorPlotImpl2D : public ReferenceComparatorPlotImpl
   std::shared_ptr<TPaveText> mQualityLabel;
 };
 
-ReferenceComparatorPlot::ReferenceComparatorPlot(TH1* referenceHistogram, const std::string& outputPath, bool scaleReference, bool drawRatioOnly, const std::string& drawOption1D, const std::string& drawOption2D)
+ReferenceComparatorPlot::ReferenceComparatorPlot(TH1* referenceHistogram,
+                                                 int referenceRun,
+                                                 const std::string& outputPath,
+                                                 bool scaleReference,
+                                                 bool drawRatioOnly,
+                                                 double legendHeight,
+                                                 const std::string& drawOption1D,
+                                                 const std::string& drawOption2D)
 {
   // histograms with integer values are promoted to floating point or double to allow correctly scaling the reference and computing the ratios
 
   // 1-D histograms
   if (referenceHistogram->InheritsFrom("TH1C") || referenceHistogram->InheritsFrom("TH1S") || referenceHistogram->InheritsFrom("TH1F")) {
-    mImplementation = std::make_shared<ReferenceComparatorPlotImpl1D<TH1F>>(referenceHistogram, outputPath, scaleReference, drawRatioOnly, drawOption1D);
+    mImplementation = std::make_shared<ReferenceComparatorPlotImpl1D<TH1F>>(referenceHistogram, referenceRun, outputPath, scaleReference, drawRatioOnly, legendHeight, drawOption1D);
   }
 
   if (referenceHistogram->InheritsFrom("TH1I") || referenceHistogram->InheritsFrom("TH1D")) {
-    mImplementation = std::make_shared<ReferenceComparatorPlotImpl1D<TH1D>>(referenceHistogram, outputPath, scaleReference, drawRatioOnly, drawOption1D);
+    mImplementation = std::make_shared<ReferenceComparatorPlotImpl1D<TH1D>>(referenceHistogram, referenceRun, outputPath, scaleReference, drawRatioOnly, legendHeight, drawOption1D);
   }
 
   // 2-D histograms
   if (referenceHistogram->InheritsFrom("TH2C") || referenceHistogram->InheritsFrom("TH2S") || referenceHistogram->InheritsFrom("TH2F")) {
-    mImplementation = std::make_shared<ReferenceComparatorPlotImpl2D<TH2F>>(referenceHistogram, outputPath, scaleReference, drawRatioOnly, drawOption2D);
+    mImplementation = std::make_shared<ReferenceComparatorPlotImpl2D<TH2F>>(referenceHistogram, referenceRun, outputPath, scaleReference, drawRatioOnly, drawOption2D);
   }
 
   if (referenceHistogram->InheritsFrom("TH2I") || referenceHistogram->InheritsFrom("TH2D")) {
-    mImplementation = std::make_shared<ReferenceComparatorPlotImpl2D<TH2D>>(referenceHistogram, outputPath, scaleReference, drawRatioOnly, drawOption2D);
+    mImplementation = std::make_shared<ReferenceComparatorPlotImpl2D<TH2D>>(referenceHistogram, referenceRun, outputPath, scaleReference, drawRatioOnly, drawOption2D);
   }
 }
 

Modules/Common/src/ReferenceComparatorTask.cxx

@@ -17,6 +17,7 @@
 
 #include "Common/ReferenceComparatorTask.h"
 #include "Common/ReferenceComparatorPlot.h"
+#include "Common/Utils.h"
 #include "QualityControl/ReferenceUtils.h"
 #include "QualityControl/QcInfoLogger.h"
 #include "QualityControl/MonitorObject.h"
@@ -104,10 +105,10 @@ void ReferenceComparatorTask::initialize(quality_control::postprocessing::Trigge
   mHistograms.clear();
 
   auto& qcdb = services.get<repository::DatabaseInterface>();
-  mNotOlderThan = std::stoi(getCustomParameter(mCustomParameters, "notOlderThan", trigger.activity, "120"));
-  mReferenceRun = std::stoi(getCustomParameter(mCustomParameters, "referenceRun", trigger.activity, "0"));
-  mIgnorePeriodForReference = std::stoi(getCustomParameter(mCustomParameters, "ignorePeriodForReference", trigger.activity, "1")) != 0;
-  mIgnorePassForReference = std::stoi(getCustomParameter(mCustomParameters, "ignorePassForReference", trigger.activity, "1")) != 0;
+  mNotOlderThan = getFromExtendedConfig<int>(trigger.activity, mCustomParameters, "notOlderThan", 120);
+  mReferenceRun = getFromExtendedConfig<int>(trigger.activity, mCustomParameters, "referenceRun", 0);
+  mIgnorePeriodForReference = getFromExtendedConfig<bool>(trigger.activity, mCustomParameters, "ignorePeriodForReference", true);
+  mIgnorePassForReference = getFromExtendedConfig<bool>(trigger.activity, mCustomParameters, "ignorePassForReference", true);
 
   ILOG(Info, Devel) << "Reference run set to '" << mReferenceRun << "' for activity " << trigger.activity << ENDM;
 
@@ -149,9 +150,10 @@ void ReferenceComparatorTask::initialize(quality_control::postprocessing::Trigge
       plotVec.push_back(fullPath);
 
       // create and store the plotter object
-      mHistograms[fullPath] = std::make_shared<ReferenceComparatorPlot>(referenceHistogram, fullOutPath,
+      mHistograms[fullPath] = std::make_shared<ReferenceComparatorPlot>(referenceHistogram, mReferenceRun, fullOutPath,
                                                                         group.normalizeReference,
                                                                         group.drawRatioOnly,
+                                                                        group.legendHeight,
                                                                         group.drawOption1D,
                                                                         group.drawOption2D);
       auto* outObject = mHistograms[fullPath]->getMainCanvas();

Modules/Common/src/ReferenceComparatorTaskConfig.cxx

@@ -34,6 +34,7 @@ ReferenceComparatorTaskConfig::ReferenceComparatorTaskConfig(std::string name, c
       dataGroupConfig.second.get<std::string>("outputPath"),
       dataGroupConfig.second.get<bool>("normalizeReference", false),
       dataGroupConfig.second.get<bool>("drawRatioOnly", false),
+      dataGroupConfig.second.get<double>("legendHeight", 0.2),
       dataGroupConfig.second.get<std::string>("drawOption1D", "HIST"),
       dataGroupConfig.second.get<std::string>("drawOption2D", "COLZ")
     };

doc/FLPsuite.md

@@ -153,7 +153,10 @@ The configuration looks like
               "referenceRun" : "500",
               "moduleName" : "QualityControl",
               "comparatorName" : "o2::quality_control_modules::common::ObjectComparatorChi2",
-              "threshold" : "0.5"
+              "threshold" : "0.2",
+              "ratioPlotRange" : "0.5",
+              "ignorePeriodForReference" : "true",
+              "ignorePassForReference" : "true"
             }
           },
           "PHYSICS": {
@@ -168,7 +171,9 @@ The configuration looks like
 The check needs the following parameters
 * `referenceRun` to specify what is the run of reference and retrieve the reference data.
 * `comparatorName` to decide how to compare, see below for their descriptions.
-* `threshold` to specifie the value used to discriminate between good and bad matches between the histograms.
+* `threshold` to specify the value used to discriminate between good and bad matches between the histograms.
+* `ratioPlotRange` to specify a custom vertical scale for the ratio plot. The vertical values are between 1.0 - range and 1.0 + range.
+* `ignorePeriodForReference`, `ignorePassForReference`: boolean flags specifying wether to ignore the period or pass names of the reference run; needed for comparing runs from different periods and/or reconstruction passes.
 
 Three comparators are provided:
 

doc/PostProcessing.md

@@ -530,14 +530,15 @@ This post-processing task draws a given set of plots in comparison with their co
 Currently the source of reference data is specified as a run-type and beam-type specific `referenceRun` number. This will be modified once a centralized way of accessing reference plots will become available in the framework.
 The `notOlderThan` option allows to ignore monitor objects that are older than a given number of seconds. A value of -1 means "no limit".
 The `ignorePeriodForReference` and `ignorePassForReference` boolean parameters control whether the period and/or pass names should be matched or not when querying the reference plots from the database.
-A value of `"1"` (default) means that the reference plots are not required to match the period and/or pass names of the current run, while a value of `"0"` means that the reference plot is retrieved only if the corresponding period and/or pass names match those of the current run.
+A value of `"true"` (default) means that the reference plots are not required to match the period and/or pass names of the current run, while a value of `"false"` means that the reference plot is retrieved only if the corresponding period and/or pass names match those of the current run.
 
 The input MonitorObjects to be processed are logically divided in **dataGroups**. Each group is configured via the following parameters:
 
 * `inputPath`: path in the QCDB where the input objects are located
 * `referencePath` (optional): specifies the path for the reference objects, if not set the `inputPath` is used
 * `outputPath`: path in the QCDB where the output objects are stored
 * `drawRatioOnly`: boolean parameter specifying wether to only draw the ratio plots, or the current/reference comparisons as well
+* `legendHeight`: space reserved for the legend above the histograms, in fractions of the pad height; if the height is set to zero, the legend is not shown
 * `drawOption1D`: the ROOT draw option to be used for the 1-D histograms
 * `drawOption2D`: the ROOT draw option to be used for the 2-D histograms
 
@@ -609,8 +610,8 @@ In the example configuration below, the relationship between the input and outpu
             "default": {
               "notOlderThan" : "300",
               "referenceRun" : "551875",
-              "ignorePeriodForReference": "1",
-              "ignorePassForReference": "1"
+              "ignorePeriodForReference": "true",
+              "ignorePassForReference": "true"
             }
           },
           "PHYSICS": {
@@ -627,6 +628,7 @@ In the example configuration below, the relationship between the input and outpu
             "outputPath": "Tracks/WithCuts",
             "normalizeReference": "true",
             "drawRatioOnly": "false",
+            "legendHeight": "0.2",  
             "drawOption1D": "E",
             "drawOption2D": "COL",
             "inputObjects": [
@@ -660,7 +662,8 @@ In the example configuration below, the relationship between the input and outpu
               "comparatorName" : "o2::quality_control_modules::common::ObjectComparatorChi2",
               "threshold" : "0.5",
               "threshold:TrackEta" : "0.2",
-              "rangeX:TrackEta" : "-3.5,-2.5"
+              "rangeX:TrackEta" : "-3.5,-2.5",
+              "ratioPlotRange" : "0.5"
             }
           }
         },