root/RooStats/HypoTestResult.h

0001 // @(#)root/roostats:$Id$
0002 // Author: Kyle Cranmer, Lorenzo Moneta, Gregory Schott, Wouter Verkerke, Sven Kreiss
0003 /*************************************************************************
0004  * Copyright (C) 1995-2008, Rene Brun and Fons Rademakers.               *
0005  * All rights reserved.                                                  *
0006  *                                                                       *
0007  * For the licensing terms see $ROOTSYS/LICENSE.                         *
0008  * For the list of contributors see $ROOTSYS/README/CREDITS.             *
0009  *************************************************************************/
0010 #ifndef ROOSTATS_HypoTestResult
0011 #define ROOSTATS_HypoTestResult
0012
0013 #include "RooStats/RooStatsUtils.h"
0014 #include "RooStats/SamplingDistribution.h"
0015
0016 #include "TNamed.h"
0017
0018 #include <memory>
0019
0020 namespace RooStats {
0021
0022    class HypoTestResult : public TNamed {
0023
0024    public:
0025
0026       /// default constructor
0027       explicit HypoTestResult(const char *name = nullptr);
0028
0029       /// copy constructor
0030       HypoTestResult(const HypoTestResult& other);
0031
0032       /// constructor from name, null and alternate p values
0033       HypoTestResult(const char* name, double nullp, double altp);
0034
0035       /// clone method, required since some data members cannot rely on the streamers to copy them
0036       TObject* Clone(const char* newname = nullptr) const override {
0037          auto out = new HypoTestResult(*this);
0038          if(newname && strlen(newname)) out->SetName(newname);
0039          return out;
0040       }
0041
0042       /// destructor
0043       ~HypoTestResult() override;
0044
0045       /// assignment operator
0046       HypoTestResult & operator=(const HypoTestResult& other);
0047
0048       /// add values from another HypoTestResult
0049       virtual void Append(const HypoTestResult *other);
0050
0051       /// Return p-value for null hypothesis
0052       virtual double NullPValue() const { return fNullPValue; }
0053
0054       /// Return p-value for alternate hypothesis
0055       virtual double AlternatePValue() const { return fAlternatePValue; }
0056
0057       /// Convert  NullPValue into a "confidence level"
0058       virtual double CLb() const { return !fBackgroundIsAlt ? NullPValue() : AlternatePValue(); }
0059
0060       /// Convert  AlternatePValue into a "confidence level"
0061       virtual double CLsplusb() const { return !fBackgroundIsAlt ? AlternatePValue() : NullPValue(); }
0062
0063       /// \f$CL_{s}\f$ is simply \f$CL_{s+b}/CL_{b}\f$ (not a method, but a quantity)
0064       virtual double CLs() const {
0065          double thisCLb = CLb();
0066          if (thisCLb == 0) {
0067             std::cout << "Error: Cannot compute CLs because CLb = 0. Returning CLs = -1\n";
0068             return -1;
0069          }
0070          double thisCLsb = CLsplusb();
0071          return thisCLsb / thisCLb;
0072       }
0073
0074       /// familiar name for the Null p-value in terms of 1-sided Gaussian significance
0075       virtual double Significance() const {return RooStats::PValueToSignificance( NullPValue() ); }
0076
0077       SamplingDistribution* GetNullDistribution(void) const { return fNullDistr.get(); }
0078       SamplingDistribution* GetAltDistribution(void) const { return fAltDistr.get(); }
0079       RooDataSet* GetNullDetailedOutput(void) const { return fNullDetailedOutput.get(); }
0080       RooDataSet* GetAltDetailedOutput(void) const { return fAltDetailedOutput.get(); }
0081       RooDataSet* GetFitInfo() const { return fFitInfo.get(); }
0082       double GetTestStatisticData(void) const { return fTestStatisticData; }
0083       const RooArgList* GetAllTestStatisticsData(void) const { return fAllTestStatisticsData.get(); }
0084       bool HasTestStatisticData(void) const;
0085
0086       void SetNullPValue(double pvalue) { fNullPValue = pvalue; }
0087       void SetNullPValueError(double err) { fNullPValueError = err; }
0088       void SetAltPValue(double pvalue) { fAlternatePValue = pvalue; }
0089       void SetAltPValueError(double err) { fAlternatePValueError = err; }
0090       void SetAltDistribution(SamplingDistribution *alt);
0091       void SetNullDistribution(SamplingDistribution *null);
0092       void SetAltDetailedOutput(RooDataSet* d) { fAltDetailedOutput.reset(d); }
0093       void SetNullDetailedOutput(RooDataSet* d) { fNullDetailedOutput.reset(d); }
0094       void SetFitInfo(RooDataSet* d) { fFitInfo.reset(d); }
0095       void SetTestStatisticData(const double tsd);
0096       void SetAllTestStatisticsData(const RooArgList* tsd);
0097
0098       void SetPValueIsRightTail(bool pr);
0099       bool GetPValueIsRightTail(void) const { return fPValueIsRightTail; }
0100
0101       void SetBackgroundAsAlt(bool l = true) { fBackgroundIsAlt = l; }
0102       bool GetBackGroundIsAlt(void) const { return fBackgroundIsAlt; }
0103
0104       /// The error on the "confidence level" of the null hypothesis
0105       double CLbError() const;
0106
0107       /// The error on the "confidence level" of the alternative hypothesis
0108       double CLsplusbError() const;
0109
0110       /// The error on the ratio \f$CL_{s+b}/CL_{b}\f$
0111       double CLsError() const;
0112
0113       /// The error on the Null p-value
0114       double NullPValueError() const;
0115
0116       /// The error on the significance, computed from NullPValueError via error propagation
0117       double SignificanceError() const;
0118
0119
0120       void Print(const Option_t* = "") const override;
0121
0122    private:
0123       void UpdatePValue(const SamplingDistribution* distr, double &pvalue, double &perror,  bool pIsRightTail);
0124
0125
0126    protected:
0127
0128       mutable double fNullPValue;             ///< p-value for the null hypothesis (small number means disfavoured)
0129       mutable double fAlternatePValue;        ///< p-value for the alternate hypothesis (small number means disfavoured)
0130       mutable double fNullPValueError;        ///< error of p-value for the null hypothesis (small number means disfavoured)
0131       mutable double fAlternatePValueError;   ///< error of p-value for the alternate hypothesis (small number means disfavoured)
0132       double fTestStatisticData;              ///< result of the test statistic evaluated on data
0133       std::unique_ptr<const RooArgList> fAllTestStatisticsData; ///< for the case of multiple test statistics, holds all the results
0134       std::unique_ptr<SamplingDistribution> fNullDistr;
0135       std::unique_ptr<SamplingDistribution> fAltDistr;
0136       std::unique_ptr<RooDataSet> fNullDetailedOutput;
0137       std::unique_ptr<RooDataSet> fAltDetailedOutput;
0138       std::unique_ptr<RooDataSet> fFitInfo;
0139       bool fPValueIsRightTail;
0140       bool fBackgroundIsAlt;
0141
0142       ClassDefOverride(HypoTestResult,5)  // Base class to represent results of a hypothesis test
0143
0144    };
0145 }
0146
0147
0148 #endif