Common: add generic checker for trending plots (#2383)

* [Common] handle std::string types in configuration helper function

The `std::string` type was not correctly handled because the standard
library does not provide an "identity" override for `std::to_string()`

* [Common] add utility class to handle the checker thresholds

The ultility class provides the following functionalities:
* stores interaction-rate-dependent threshold values
* stores optional axis ranges on which the check should be restricted
* provides the code to retrieve the threshold and range values from the custom parameters
* provides a function to retrieve the optimal threshold values for a given interaction rate

* [Common] added generic checker from trend graphs

The checker is designed to verify that the values of trend graphs are
within given minimum and maximum limits.
The limits can be specified as fixed values, or values relative to either
the mean or the standard deviation of a given set of graph points.

* [Common] improved name of one variable

* [Common] added documentation for TrendCheck

Modules/Common/CMakeLists.txt

@@ -31,6 +31,8 @@ target_sources(O2QcCommon
                        src/ReferenceComparatorTask.cxx
                        src/ReferenceComparatorTaskConfig.cxx
                        src/ReferenceComparatorCheck.cxx
+                       src/CheckerThresholdsConfig.cxx
+                       src/TrendCheck.cxx
                        src/NonEmpty.cxx
                        src/MeanIsAbove.cxx
                        src/TH1Reductor.cxx
@@ -70,6 +72,7 @@ add_root_dictionary(O2QcCommon
                             include/Common/ObjectComparatorKolmogorov.h
                             include/Common/ReferenceComparatorTask.h
                             include/Common/ReferenceComparatorCheck.h
+                            include/Common/TrendCheck.h
                             include/Common/MeanIsAbove.h
                             include/Common/TH1Ratio.h
                             include/Common/TH2Ratio.h

Modules/Common/include/Common/CheckerThresholdsConfig.h

@@ -0,0 +1,71 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+///
+/// \file   CheckerThresholdsConfig.h
+/// \author Andrea Ferrero
+/// \brief  Utility class handling thresholds and axis ranges and retrieve them from the custom parameters
+///
+
+#ifndef QC_MODULE_COMMON_CHECKERTHRESHOLDSCONFIG_H
+#define QC_MODULE_COMMON_CHECKERTHRESHOLDSCONFIG_H
+
+#include "QualityControl/Activity.h"
+#include "QualityControl/CustomParameters.h"
+
+#include <string>
+#include <optional>
+#include <array>
+#include <vector>
+
+using namespace o2::quality_control::core;
+
+namespace o2::quality_control_modules::common
+{
+
+namespace internal
+{
+class Thresholds;
+class XYRanges;
+} // namespace internal
+
+class CheckerThresholdsConfig
+{
+ public:
+  CheckerThresholdsConfig(const CustomParameters& customParameters, const Activity& activity);
+  ~CheckerThresholdsConfig() = default;
+
+  /// \brief function to retrieve the thresholds for a given interaction rate, if available
+  std::array<std::optional<std::pair<double, double>>, 2> getThresholdsForPlot(const std::string& plotName, double rate);
+
+  /// \brief optional X-Y ranges over which the check must be restricted
+  std::array<std::optional<std::pair<double, double>>, 2> getRangesForPlot(const std::string& plotName);
+
+ private:
+  void initThresholdsForPlot(const std::string& plotName);
+  void initRangesForPlot(const std::string& plotName);
+
+  CustomParameters mCustomParameters;
+  Activity mActivity;
+
+  /// vectors of [min,max,rate] tuples. The first two values are the minimum and maximum threshold values,
+  /// and the third is the associated reference interaction rate (optional)
+  std::array<std::shared_ptr<internal::Thresholds>, 2> mDefaultThresholds;
+  std::array<std::unordered_map<std::string, std::shared_ptr<internal::Thresholds>>, 2> mThresholds;
+
+  /// \brief optional X-Y ranges over which the check must be restricted
+  std::array<std::shared_ptr<internal::XYRanges>, 2> mDefaultRanges;
+  std::array<std::unordered_map<std::string, std::shared_ptr<internal::XYRanges>>, 2> mRanges;
+};
+
+} // namespace o2::quality_control_modules::common
+
+#endif // QC_MODULE_COMMON_CHECKERTHRESHOLDSCONFIG_H

Modules/Common/include/Common/LinkDef.h

@@ -25,6 +25,7 @@
 #pragma link C++ class o2::quality_control_modules::common::ObjectComparatorKolmogorov + ;
 #pragma link C++ class o2::quality_control_modules::common::ReferenceComparatorTask + ;
 #pragma link C++ class o2::quality_control_modules::common::ReferenceComparatorCheck + ;
+#pragma link C++ class o2::quality_control_modules::common::TrendCheck + ;
 #pragma link C++ class o2::quality_control_modules::common::WorstOfAllAggregator + ;
 #pragma link C++ class o2::quality_control_modules::common::IncreasingEntries + ;
 #pragma link C++ class o2::quality_control_modules::common::TH1SliceReductor + ;

Modules/Common/include/Common/TrendCheck.h

@@ -0,0 +1,83 @@
+// Copyright 2019-2020 CERN and copyright holders of ALICE O2.
+// See https://alice-o2.web.cern.ch/copyright for details of the copyright holders.
+// All rights not expressly granted are reserved.
+//
+// This software is distributed under the terms of the GNU General Public
+// License v3 (GPL Version 3), copied verbatim in the file "COPYING".
+//
+// In applying this license CERN does not waive the privileges and immunities
+// granted to it by virtue of its status as an Intergovernmental Organization
+// or submit itself to any jurisdiction.
+
+///
+/// \file   TrendCheck.h
+/// \author Andrea Ferrero
+/// \brief  Generic checker for trending graphs
+///
+
+#ifndef QC_MODULE_COMMON_TRENDCHECK_H
+#define QC_MODULE_COMMON_TRENDCHECK_H
+
+#include "QualityControl/CheckInterface.h"
+
+#include <optional>
+#include <array>
+#include <unordered_map>
+
+class TGraph;
+class TObject;
+
+using namespace o2::quality_control::core;
+
+namespace o2::quality_control_modules::common
+{
+
+class CheckerThresholdsConfig;
+
+/// \brief  Generic checker for trending graphs
+///
+/// \author Andrea Ferrero
+class TrendCheck : public o2::quality_control::checker::CheckInterface
+{
+ public:
+  /// Default constructor
+  TrendCheck() = default;
+  /// Destructor
+  ~TrendCheck() override = default;
+
+  void configure() override;
+  Quality check(std::map<std::string, std::shared_ptr<MonitorObject>>* moMap) override;
+  void beautify(std::shared_ptr<MonitorObject> mo, Quality checkResult = Quality::Null) override;
+  std::string getAcceptedType() override;
+
+  void startOfActivity(const Activity& activity) override;
+  void endOfActivity(const Activity& activity) override;
+
+  ClassDefOverride(TrendCheck, 1);
+
+ private:
+  enum ThresholdsMode {
+    ExpectedRange,
+    DeviationFromMean,
+    StdDeviation
+  };
+
+  std::array<std::optional<std::pair<double, double>>, 2> getThresholds(std::string key, TGraph* graph);
+  void getGraphsFromObject(TObject* object, std::vector<TGraph*>& graphs);
+  double getInteractionRate();
+
+  Activity mActivity;
+  ThresholdsMode mTrendCheckMode{ ExpectedRange };
+  int mNPointsForAverage{ 0 };
+  std::pair<float, float> mQualityLabelPosition{ 0.12, 0.8 };
+  std::pair<float, float> mQualityLabelSize{ 0.5, 0.07 };
+  std::shared_ptr<CheckerThresholdsConfig> mThresholds;
+  std::unordered_map<std::string, std::vector<std::pair<double, std::pair<double, double>>>> mAverageTrend;
+  std::unordered_map<std::string, std::vector<std::pair<double, std::pair<double, double>>>> mThresholdsTrendBad;
+  std::unordered_map<std::string, std::vector<std::pair<double, std::pair<double, double>>>> mThresholdsTrendMedium;
+  std::unordered_map<std::string, Quality> mQualities;
+};
+
+} // namespace o2::quality_control_modules::common
+
+#endif // QC_MODULE_COMMON_TRENDCHECK_H