Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
xRooFit.h
Go to the documentation of this file.
1/*
2 * Project: xRooFit
3 * Author:
4 * Will Buttinger, RAL 2022
5 *
6 * Copyright (c) 2022, CERN
7 *
8 * Redistribution and use in source and binary forms,
9 * with or without modification, are permitted according to the terms
10 * listed in LICENSE (http://roofit.sourceforge.net/license.txt)
11 */
12#include "Config.h"
13
14// when not using the namespace will use the once pragma.
15// when using the namespace (as happens in the ROOT build of xRooFit) then
16// will effectively use an include guard
17#ifdef XROOFIT_USE_PRAGMA_ONCE
18#pragma once
19#endif
20#if (!defined(XROOFIT_USE_PRAGMA_ONCE) && !defined(XROOFIT_XROOFIT_H)) || \
21 (defined(XROOFIT_USE_PRAGMA_ONCE) && !defined(XROOFIT_XROOFIT_H_XROOFIT))
22#ifndef XROOFIT_USE_PRAGMA_ONCE
23#define XROOFIT_XROOFIT_H
24#else
25#define XROOFIT_XROOFIT_H_XROOFIT
26// even with using pragma once, need include guard otherwise cannot include this header
27// as part of an interpreted file ... the other headers in xRooFit are similarly affected
28// however for now users of xRooFit should only need to include the main xRooFit header to use it all
29// in future we should try removing the pragma once altogether (undef XROOFIT_USE_PRAGMA_ONCE)
30// and see if it has negative consequences anywhere
31#endif
32
33/**
34 * This is the main include for the xRooFit project.
35 * Including this should give you access to all xRooFit features
36 */
37
38class RooAbsData;
40class RooFitResult;
41class RooAbsPdf;
42class RooAbsReal;
43class RooLinkedList;
44class RooWorkspace;
45
46#include "Fit/FitConfig.h"
47
48#include "RooCmdArg.h"
49#include "TNamed.h"
50
51class TCanvas;
52
53#include <memory>
54
56
57class xRooNLLVar;
58
59class xRooFit {
60
61public:
62 static const char *GetVersion();
63 static const char *GetVersionDate();
64
65 // Extra options for NLL creation:
66 static RooCmdArg ReuseNLL(bool flag); // if should try to reuse the NLL object when it changes dataset
67 static RooCmdArg Tolerance(double value);
68 static RooCmdArg StrategySequence(const char *stratSeq); // control minimization strategy sequence
69 static constexpr double OBS = std::numeric_limits<double>::quiet_NaN();
70
71 // Helper function for matching precision of a value and its error
72 static std::pair<double, double> matchPrecision(const std::pair<double, double> &in);
73
74 // Static methods that work with the 'first class' object types:
75 // Pdfs: RooAbsPdf
76 // Datasets: std::pair<RooAbsData,const RooAbsCollection>
77 // NLLOptions: RooLinkedList
78 // FitOptions: ROOT::Fit::FitConfig
79
80 // fit result flags in its constPars list which are global observables with the "global" attribute
81 static std::pair<std::shared_ptr<RooAbsData>, std::shared_ptr<const RooAbsCollection>>
82 generateFrom(RooAbsPdf &pdf, const RooFitResult &fr, bool expected = false, int seed = 0);
83 static std::shared_ptr<const RooFitResult>
84 fitTo(RooAbsPdf &pdf, const std::pair<std::shared_ptr<RooAbsData>, std::shared_ptr<const RooAbsCollection>> &data,
85 const RooLinkedList &nllOpts, const ROOT::Fit::FitConfig &fitConf);
86 static std::shared_ptr<const RooFitResult> fitTo(RooAbsPdf &pdf,
87 const std::pair<RooAbsData *, const RooAbsCollection *> &data,
88 const RooLinkedList &nllOpts, const ROOT::Fit::FitConfig &fitConf);
89
90 static xRooNLLVar createNLL(const std::shared_ptr<RooAbsPdf> pdf, const std::shared_ptr<RooAbsData> data,
91 const RooLinkedList &nllOpts);
92 static xRooNLLVar createNLL(RooAbsPdf &pdf, RooAbsData *data, const RooLinkedList &nllOpts);
93 static xRooNLLVar createNLL(RooAbsPdf &pdf, RooAbsData *data, const RooCmdArg &arg1 = RooCmdArg::none(),
94 const RooCmdArg &arg2 = RooCmdArg::none(), const RooCmdArg &arg3 = RooCmdArg::none(),
95 const RooCmdArg &arg4 = RooCmdArg::none(), const RooCmdArg &arg5 = RooCmdArg::none(),
96 const RooCmdArg &arg6 = RooCmdArg::none(), const RooCmdArg &arg7 = RooCmdArg::none(),
97 const RooCmdArg &arg8 = RooCmdArg::none());
98
99 static std::shared_ptr<ROOT::Fit::FitConfig> createFitConfig(); // obtain instance of default fit configuration
100 static std::shared_ptr<RooLinkedList> createNLLOptions(); // obtain instance of default nll options
101 static std::shared_ptr<RooLinkedList> defaultNLLOptions(); // access default NLL options for modifications
102 static std::shared_ptr<ROOT::Fit::FitConfig> defaultFitConfig();
103 static ROOT::Math::IOptions *defaultFitConfigOptions();
104
105 static std::shared_ptr<const RooFitResult> minimize(RooAbsReal &nll,
106 const std::shared_ptr<ROOT::Fit::FitConfig> &fitConfig = nullptr,
107 const std::shared_ptr<RooLinkedList> &nllOpts = nullptr);
108 static int minos(RooAbsReal &nll, const RooFitResult &ufit, const char *parName = "",
109 const std::shared_ptr<ROOT::Fit::FitConfig> &_fitConfig = nullptr);
110
111 // this class is used to store a shared_ptr in a TDirectory's List, so that retrieval of cached fits
112 // can share the fit result (and avoid re-reading from disk as well)
113 class StoredFitResult : public TNamed {
114 public:
116 StoredFitResult(const std::shared_ptr<RooFitResult> &_fr);
117
118 public:
119 std::shared_ptr<RooFitResult> fr; //!
121 };
122
123 // can't use an enum class because pyROOT doesn't handle it
125 public:
126 enum Type {
127 // basic likelihood ratio
128 tmu = -1,
129 // upper limit test statistics
130 qmu = -2,
131 qmutilde = -3,
132 // discovery test statistics
133 q0 = -4,
134 uncappedq0 = -5,
135 u0 = -5
136 };
137 };
138
140
141 public:
142 typedef std::vector<std::pair<double, int>> IncompatFunc;
143
144 enum PLLType {
145 TwoSided = 0,
146 OneSidedPositive, // for exclusions
147 OneSidedNegative, // for discovery
148 OneSidedAbsolute, // for exclusions by magnitude
149 Uncapped, // for discovery with interest in deficits as well as excesses
150 Unknown
151 };
152
153 // The incompatibility function (taking mu_hat as an input) is defined by its transitions
154 // it takes values of -1, 0, or 1 ... when it 0 that means mu_hat is compatible with the hypothesis
155 // Standard incompatibility functions are parameterized by mu
156 // Note: the default value is taken to be 1, so an empty vector is function=1
158 {
159 std::vector<std::pair<double, int>> out;
160 if (type == TwoSided) {
161 // standard PLL
162 } else if (type == OneSidedPositive) {
163 out.emplace_back(std::make_pair(mu, 0)); // becomes compatible @ mu_hat = mu
164 } else if (type == OneSidedNegative) {
165 out.emplace_back(std::make_pair(-std::numeric_limits<double>::infinity(), 0)); // compatible at -inf
166 out.emplace_back(std::make_pair(mu, 1)); // becomes incompatible at mu_hat = mu
167 } else if (type == OneSidedAbsolute) {
168 out.emplace_back(std::make_pair(-std::numeric_limits<double>::infinity(), 0)); // compatible at -inf
169 out.emplace_back(std::make_pair(-mu, 1)); // incompatible @ mu_hat = -mu
170 out.emplace_back(std::make_pair(mu, 0)); // compatible again @ mu_hat = mu
171 } else if (type == Uncapped) {
172 out.emplace_back(std::make_pair(-std::numeric_limits<double>::infinity(), -1)); // reversed at -inf
173 out.emplace_back(std::make_pair(mu, 1)); // becomes normal @ mu_hat = mu
174 } else {
175 throw std::runtime_error("Unknown PLL Type");
176 }
177 return out;
178 }
179
180 // inverse of PValue function
181 static double k(const IncompatFunc &compatRegions, double pValue, double poiVal, double poiPrimeVal,
182 double sigma_mu = 0, double mu_low = -std::numeric_limits<double>::infinity(),
183 double mu_high = std::numeric_limits<double>::infinity());
184
185 static double k(const PLLType &pllType, double pValue, double mu, double mu_prime, double sigma_mu = 0,
186 double mu_low = -std::numeric_limits<double>::infinity(),
187 double mu_high = std::numeric_limits<double>::infinity())
188 {
189 return k(IncompatibilityFunction(pllType, mu), pValue, mu, mu_prime, sigma_mu, mu_low, mu_high);
190 }
191
192 // Recommend sigma_mu = |mu - mu_prime|/sqrt(pll_mu(asimov_mu_prime))
193 static double PValue(const IncompatFunc &compatRegions, double k, double mu, double mu_prime, double sigma_mu = 0,
194 double mu_low = -std::numeric_limits<double>::infinity(),
195 double mu_high = std::numeric_limits<double>::infinity());
196
197 static double PValue(const PLLType &pllType, double k, double mu, double mu_prime, double sigma_mu = 0,
198 double mu_low = -std::numeric_limits<double>::infinity(),
199 double mu_high = std::numeric_limits<double>::infinity())
200 {
201 return PValue(IncompatibilityFunction(pllType, mu), k, mu, mu_prime, sigma_mu, mu_low, mu_high);
202 }
203
204 static double Phi_m(double mu, double mu_prime, double a, double sigma, const IncompatFunc &compatRegions);
205
206 static int CompatFactor(const IncompatFunc &func, double mu_hat);
207
208 static int CompatFactor(int type, double mu, double mu_hat)
209 {
210 return CompatFactor(IncompatibilityFunction((PLLType)type, mu), mu_hat);
211 }
212
213 // converts pvalues to significances and finds where they equal the target pvalue
214 // return is x-axis value with potentially an error on that value if input pVals had errors
215 // static RooRealVar FindLimit(TGraph *pVals, double target_pVal = 0.05);
216 };
217
218 static std::shared_ptr<RooLinkedList> sDefaultNLLOptions;
219 static std::shared_ptr<ROOT::Fit::FitConfig> sDefaultFitConfig;
220
221 // Run hypothesis test(s) on the given pdf
222 // Uses hypoPoint binning on model parameters to determine points to scan
223 // if hypoPoint binning has nBins==0 then will auto-scan (assumes CL=95%, can override with setStringAttribute)
224 // TODO: specifying number of null and alt toys per point
225 static TCanvas *
226 hypoTest(RooWorkspace &w, const xRooFit::Asymptotics::PLLType &pllType = xRooFit::Asymptotics::Unknown)
227 {
228 return hypoTest(w, 0, 0, pllType);
229 }
230 static TCanvas *hypoTest(RooWorkspace &w, int nToysNull, int nToysAlt,
231 const xRooFit::Asymptotics::PLLType &pllType = xRooFit::Asymptotics::Unknown);
232};
233
235
236#include "xRooHypoSpace.h"
237#include "xRooNLLVar.h"
238#include "xRooNode.h"
239
240#endif // include guard
#define a(i)
Definition RSha256.hxx:99
#define ClassDef(name, id)
Definition Rtypes.h:337
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void data
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void value
Option_t Option_t TPoint TPoint const char GetTextMagnitude GetFillStyle GetLineColor GetLineWidth GetMarkerStyle GetTextAlign GetTextColor GetTextSize void char Point_t Rectangle_t WindowAttributes_t Float_t Float_t Float_t Int_t Int_t UInt_t UInt_t Rectangle_t Int_t Int_t Window_t TString Int_t GCValues_t GetPrimarySelectionOwner GetDisplay GetScreen GetColormap GetNativeEvent const char const char dpyName wid window const char font_name cursor keysym reg const char only_if_exist regb h Point_t winding char text const char depth char const char Int_t count const char ColorStruct_t color const char Pixmap_t Pixmap_t PictureAttributes_t attr const char char ret_data h unsigned char height h Atom_t Int_t ULong_t ULong_t unsigned char prop_list Atom_t Atom_t Atom_t Time_t type
static double k(const IncompatFunc &compatRegions, double pValue, double poiVal, double poiPrimeVal, double sigma_mu=0, double mu_low=-std::numeric_limits< double >::infinity(), double mu_high=std::numeric_limits< double >::infinity())
static double PValue(const PLLType &pllType, double k, double mu, double mu_prime, double sigma_mu=0, double mu_low=-std::numeric_limits< double >::infinity(), double mu_high=std::numeric_limits< double >::infinity())
Definition xRooFit.h:197
static int CompatFactor(int type, double mu, double mu_hat)
Definition xRooFit.h:208
static IncompatFunc IncompatibilityFunction(const PLLType &type, double mu)
Definition xRooFit.h:157
std::vector< std::pair< double, int > > IncompatFunc
Definition xRooFit.h:142
static double k(const PLLType &pllType, double pValue, double mu, double mu_prime, double sigma_mu=0, double mu_low=-std::numeric_limits< double >::infinity(), double mu_high=std::numeric_limits< double >::infinity())
Definition xRooFit.h:185
static double PValue(const IncompatFunc &compatRegions, double k, double mu, double mu_prime, double sigma_mu=0, double mu_low=-std::numeric_limits< double >::infinity(), double mu_high=std::numeric_limits< double >::infinity())
static TCanvas * hypoTest(RooWorkspace &w, const xRooFit::Asymptotics::PLLType &pllType=xRooFit::Asymptotics::Unknown)
Definition xRooFit.h:226
static std::shared_ptr< RooLinkedList > sDefaultNLLOptions
Definition xRooFit.h:218
static std::shared_ptr< ROOT::Fit::FitConfig > sDefaultFitConfig
Definition xRooFit.h:219
static TCanvas * hypoTest(RooWorkspace &w, int nToysNull, int nToysAlt, const xRooFit::Asymptotics::PLLType &pllType=xRooFit::Asymptotics::Unknown)
This xRooNLLVar object has several special methods, e.g.
Definition xRooNLLVar.h:59
Class describing the configuration of the fit, options and parameter settings using the ROOT::Fit::Pa...
Definition FitConfig.h:47
Generic interface for defining configuration options of a numerical algorithm.
Definition IOptions.h:28
Abstract container object that can hold multiple RooAbsArg objects.
Abstract base class for binned and unbinned datasets.
Definition RooAbsData.h:57
Abstract interface for all probability density functions.
Definition RooAbsPdf.h:40
Abstract base class for objects that represent a real value and implements functionality common to al...
Definition RooAbsReal.h:59
Named container for two doubles, two integers two object points and three string pointers that can be...
Definition RooCmdArg.h:26
static const RooCmdArg & none()
Return reference to null argument.
Definition RooCmdArg.cxx:48
RooFitResult is a container class to hold the input and output of a PDF fit to a dataset.
Collection class for internal use, storing a collection of RooAbsArg pointers in a doubly linked list...
Persistable container for RooFit projects.
The Canvas class.
Definition TCanvas.h:23
The TNamed class is the base class for all named ROOT classes.
Definition TNamed.h:29
const Double_t sigma
#define BEGIN_XROOFIT_NAMESPACE
Definition Config.h:24
#define END_XROOFIT_NAMESPACE
Definition Config.h:25