From 626e7c400441cc0187832df11d89ea5d1c5e2b87 Mon Sep 17 00:00:00 2001
From: Barthelemy <barthelemy.von.haller@cern.ch>
Date: Wed, 26 Jun 2024 12:22:01 +0200
Subject: [PATCH] add beautify and doc

---
 .../include/QualityControl/ReferenceUtils.h   |  5 +-
 .../include/Common/ReferenceComparatorTask.h  |  1 -
 doc/Advanced.md                               | 71 +++++++++++++++++--
 3 files changed, 68 insertions(+), 9 deletions(-)

diff --git a/Framework/include/QualityControl/ReferenceUtils.h b/Framework/include/QualityControl/ReferenceUtils.h
index 304d8edcde..2f096ac9b3 100644
--- a/Framework/include/QualityControl/ReferenceUtils.h
+++ b/Framework/include/QualityControl/ReferenceUtils.h
@@ -50,10 +50,7 @@ static std::shared_ptr<quality_control::core::MonitorObject> getReferencePlot(qu
   if (!o2::quality_control::core::RepoPathUtils::splitObjectPath(fullPath, path, name)) {
     return nullptr;
   }
-  // retrieve MO from CCDB
-  auto mo = qcdb->retrieveMO(path, name, timeStamp, activity);
-
-  return mo;
+  return qcdb->retrieveMO(path, name, timeStamp, activity);
 }
 
 } // namespace o2::quality_control_modules::common
diff --git a/Modules/Common/include/Common/ReferenceComparatorTask.h b/Modules/Common/include/Common/ReferenceComparatorTask.h
index 57f582c458..5990f50fec 100644
--- a/Modules/Common/include/Common/ReferenceComparatorTask.h
+++ b/Modules/Common/include/Common/ReferenceComparatorTask.h
@@ -24,7 +24,6 @@
 #include <TH1.h>
 #include <TPad.h>
 #include <TCanvas.h>
-#include <TPaveText.h>
 #include <TText.h>
 #include <string>
 #include <map>
diff --git a/doc/Advanced.md b/doc/Advanced.md
index 2d396d147a..d0f0ef9add 100644
--- a/doc/Advanced.md
+++ b/doc/Advanced.md
@@ -1309,10 +1309,73 @@ void customize(std::vector<ConfigParamSpec>& workflowOptions)
 ```
 
 ## Reference data
-TODO
-- PP task -> pointer
-- Checker -> if PP -> pointer
-- Checker on TH1 -> describe here
+
+A reference object is an object from a previous run. It is usually used as a point of comparison. 
+
+### Get a reference plot
+
+To retrieve a reference plot in your Check, use 
+```
+  std::shared_ptr<MonitorObject> retrieveReference(std::string path, int referenceRun, Activity activity);
+```
+- `path` : the path of the object _without the provenance (e.g. `qc`)
+- `referenceRun` : the run of reference
+- `activity` : the current activity
+
+If the reference is not found it will return a `nullptr` and issue a warning. 
+
+### Compare to a reference plot
+
+The check `ReferenceComparatorCheck` in `Common` compares objects to their reference. 
+
+TODO beautify
+
+The configuration looks like 
+```
+      "QcCheck": {
+        "active": "true",
+        "className": "o2::quality_control_modules::common::ReferenceComparatorCheck",
+        "moduleName": "QcCommon",
+        "policy": "OnAny",
+        "detectorName": "TST",
+        "dataSource": [{
+          "type": "Task",
+          "name": "QcTask",
+          "MOs": ["example"]
+        }],
+        "extendedCheckParameters": {
+          "default": {
+            "default": {
+              "referenceRun" : "500",
+              "moduleName" : "QualityControl",
+              "comparatorName" : "o2::quality_control_modules::common::ObjectComparatorChi2",
+              "threshold" : "0.5"
+            }
+          },
+          "PHYSICS": {
+            "PROTON-PROTON": {
+              "referenceRun" : "551890"
+            }
+          }
+        }
+      }
+```
+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.
+
+Three comparator are provided:
+1. `o2::quality_control_modules::common::ObjectComparatorDeviation`: comparison based on the average relative deviation between the bins of the current and reference histograms; the `threshold` parameter represent in this case the maximum allowed deviation
+2. `o2::quality_control_modules::common::ObjectComparatorChi2`: comparison based on a standard chi2 test between the current and reference histograms; the `threshold` parameter represent in this case the minimum allowed chi2 probability
+3. `o2::quality_control_modules::common::ObjectComparatorKolmogorov`: comparison based on a standard Kolmogorov test between the current and reference histograms; the `threshold` parameter represent in this case the minimum allowed Kolmogorov probability
+
+Note that you can easily specify different reference runs for different run types and beam types. 
+
+### Generate a canvas combining both the current and reference ratio histogram
+
+The postprocessing task ReferenceComparatorTask draws a given set of plots in comparison with their corresponding references, both as superimposed histograms and as current/reference ratio histograms.
+See the details [here](https://github.com/AliceO2Group/QualityControl/blob/master/doc/PostProcessing.md#the-referencecomparatortask-class).
 
 ## Configuration files details