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       /// destructor
0036       ~HypoTestResult() override;
0037
0038       /// assignment operator
0039       HypoTestResult & operator=(const HypoTestResult& other);
0040
0041       /// add values from another HypoTestResult
0042       virtual void Append(const HypoTestResult *other);
0043
0044       /// Return p-value for null hypothesis
0045       virtual double NullPValue() const { return fNullPValue; }
0046
0047       /// Return p-value for alternate hypothesis
0048       virtual double AlternatePValue() const { return fAlternatePValue; }
0049
0050       /// Convert  NullPValue into a "confidence level"
0051       virtual double CLb() const { return !fBackgroundIsAlt ? NullPValue() : AlternatePValue(); }
0052
0053       /// Convert  AlternatePValue into a "confidence level"
0054       virtual double CLsplusb() const { return !fBackgroundIsAlt ? AlternatePValue() : NullPValue(); }
0055
0056       /// \f$CL_{s}\f$ is simply \f$CL_{s+b}/CL_{b}\f$ (not a method, but a quantity)
0057       virtual double CLs() const {
0058          double thisCLb = CLb();
0059          if (thisCLb == 0) {
0060             std::cout << "Error: Cannot compute CLs because CLb = 0. Returning CLs = -1\n";
0061             return -1;
0062          }
0063          double thisCLsb = CLsplusb();
0064          return thisCLsb / thisCLb;
0065       }
0066
0067       /// familiar name for the Null p-value in terms of 1-sided Gaussian significance
0068       virtual double Significance() const {return RooStats::PValueToSignificance( NullPValue() ); }
0069
0070       SamplingDistribution* GetNullDistribution(void) const { return fNullDistr; }
0071       SamplingDistribution* GetAltDistribution(void) const { return fAltDistr; }
0072       RooDataSet* GetNullDetailedOutput(void) const { return fNullDetailedOutput; }
0073       RooDataSet* GetAltDetailedOutput(void) const { return fAltDetailedOutput; }
0074       RooDataSet* GetFitInfo() const { return fFitInfo.get(); }
0075       double GetTestStatisticData(void) const { return fTestStatisticData; }
0076       const RooArgList* GetAllTestStatisticsData(void) const { return fAllTestStatisticsData; }
0077       bool HasTestStatisticData(void) const;
0078
0079       void SetNullPValue(double pvalue) { fNullPValue = pvalue; }
0080       void SetNullPValueError(double err) { fNullPValueError = err; }
0081       void SetAltPValue(double pvalue) { fAlternatePValue = pvalue; }
0082       void SetAltPValueError(double err) { fAlternatePValueError = err; }
0083       void SetAltDistribution(SamplingDistribution *alt);
0084       void SetNullDistribution(SamplingDistribution *null);
0085       void SetAltDetailedOutput(RooDataSet* d) { fAltDetailedOutput = d; }
0086       void SetNullDetailedOutput(RooDataSet* d) { fNullDetailedOutput = d; }
0087       void SetFitInfo(RooDataSet* d) { fFitInfo.reset(d); }
0088       void SetTestStatisticData(const double tsd);
0089       void SetAllTestStatisticsData(const RooArgList* tsd);
0090
0091       void SetPValueIsRightTail(bool pr);
0092       bool GetPValueIsRightTail(void) const { return fPValueIsRightTail; }
0093
0094       void SetBackgroundAsAlt(bool l = true) { fBackgroundIsAlt = l; }
0095       bool GetBackGroundIsAlt(void) const { return fBackgroundIsAlt; }
0096
0097       /// The error on the "confidence level" of the null hypothesis
0098       double CLbError() const;
0099
0100       /// The error on the "confidence level" of the alternative hypothesis
0101       double CLsplusbError() const;
0102
0103       /// The error on the ratio \f$CL_{s+b}/CL_{b}\f$
0104       double CLsError() const;
0105
0106       /// The error on the Null p-value
0107       double NullPValueError() const;
0108
0109       /// The error on the significance, computed from NullPValueError via error propagation
0110       double SignificanceError() const;
0111
0112
0113       void Print(const Option_t* = "") const override;
0114
0115    private:
0116       void UpdatePValue(const SamplingDistribution* distr, double &pvalue, double &perror,  bool pIsRightTail);
0117
0118
0119    protected:
0120
0121       mutable double fNullPValue;             ///< p-value for the null hypothesis (small number means disfavoured)
0122       mutable double fAlternatePValue;        ///< p-value for the alternate hypothesis (small number means disfavoured)
0123       mutable double fNullPValueError;        ///< error of p-value for the null hypothesis (small number means disfavoured)
0124       mutable double fAlternatePValueError;   ///< error of p-value for the alternate hypothesis (small number means disfavoured)
0125       double fTestStatisticData;              ///< result of the test statistic evaluated on data
0126       const RooArgList* fAllTestStatisticsData; ///< for the case of multiple test statistics, holds all the results
0127       SamplingDistribution *fNullDistr;
0128       SamplingDistribution *fAltDistr;
0129       RooDataSet* fNullDetailedOutput;
0130       RooDataSet* fAltDetailedOutput;
0131       std::unique_ptr<RooDataSet> fFitInfo;
0132       bool fPValueIsRightTail;
0133       bool fBackgroundIsAlt;
0134
0135       ClassDefOverride(HypoTestResult,4)  // Base class to represent results of a hypothesis test
0136
0137    };
0138 }
0139
0140
0141 #endif