ROOT  6.06/09
Reference Guide
TLinearFitter.h
Go to the documentation of this file.
1 // @(#)root/minuit:$Id$
2 // Author: Anna Kreshuk 04/03/2005
3 
4 /*************************************************************************
5  * Copyright (C) 1995-2005, Rene Brun and Fons Rademakers. *
6  * All rights reserved. *
7  * *
8  * For the licensing terms see $ROOTSYS/LICENSE. *
9  * For the list of contributors see $ROOTSYS/README/CREDITS. *
10  *************************************************************************/
11 
12 #ifndef ROOT_TLinearFitter
13 #define ROOT_TLinearFitter
14 
15 //////////////////////////////////////////////////////////////////////////
16 //
17 // The Linear Fitter - fitting functions that are LINEAR IN PARAMETERS
18 //
19 // Linear fitter is used to fit a set of data points with a linear
20 // combination of specified functions. Note, that "linear" in the name
21 // stands only for the model dependency on parameters, the specified
22 // functions can be nonlinear.
23 // The general form of this kind of model is
24 //
25 // y(x) = a[0] + a[1]*f[1](x)+...a[n]*f[n](x)
26 //
27 // Functions f are fixed functions of x. For example, fitting with a
28 // polynomial is linear fitting in this sense.
29 //
30 // The fitting method
31 //
32 // The fit is performed using the Normal Equations method with Cholesky
33 // decomposition.
34 //
35 // Why should it be used?
36 //
37 // The linear fitter is considerably faster than general non-linear
38 // fitters and doesn't require to set the initial values of parameters.
39 //
40 // Using the fitter:
41 //
42 // 1.Adding the data points:
43 // 1.1 To store or not to store the input data?
44 // - There are 2 options in the constructor - to store or not
45 // store the input data. The advantages of storing the data
46 // are that you'll be able to reset the fitting model without
47 // adding all the points again, and that for very large sets
48 // of points the chisquare is calculated more precisely.
49 // The obvious disadvantage is the amount of memory used to
50 // keep all the points.
51 // - Before you start adding the points, you can change the
52 // store/not store option by StoreData() method.
53 // 1.2 The data can be added:
54 // - simply point by point - AddPoint() method
55 // - an array of points at once:
56 // If the data is already stored in some arrays, this data
57 // can be assigned to the linear fitter without physically
58 // coping bytes, thanks to the Use() method of
59 // TVector and TMatrix classes - AssignData() method
60 //
61 // 2.Setting the formula
62 // 2.1 The linear formula syntax:
63 // -Additive parts are separated by 2 plus signes "++"
64 // --for example "1 ++ x" - for fitting a straight line
65 // -All standard functions, undrestood by TFormula, can be used
66 // as additive parts
67 // --TMath functions can be used too
68 // -Functions, used as additive parts, shouldn't have any parameters,
69 // even if those parameters are set.
70 // --for example, if normalizing a sum of a gaus(0, 1) and a
71 // gaus(0, 2), don't use the built-in "gaus" of TFormula,
72 // because it has parameters, take TMath::Gaus(x, 0, 1) instead.
73 // -Polynomials can be used like "pol3", .."polN"
74 // -If fitting a more than 3-dimensional formula, variables should
75 // be numbered as follows:
76 // -- x0, x1, x2... For example, to fit "1 ++ x0 ++ x1 ++ x2 ++ x3*x3"
77 // 2.2 Setting the formula:
78 // 2.2.1 If fitting a 1-2-3-dimensional formula, one can create a
79 // TF123 based on a linear expression and pass this function
80 // to the fitter:
81 // --Example:
82 // TLinearFitter *lf = new TLinearFitter();
83 // TF2 *f2 = new TF2("f2", "x ++ y ++ x*x*y*y", -2, 2, -2, 2);
84 // lf->SetFormula(f2);
85 // --The results of the fit are then stored in the function,
86 // just like when the TH1::Fit or TGraph::Fit is used
87 // --A linear function of this kind is by no means different
88 // from any other function, it can be drawn, evaluated, etc.
89 // 2.2.2 There is no need to create the function if you don't want to,
90 // the formula can be set by expression:
91 // --Example:
92 // // 2 is the number of dimensions
93 // TLinearFitter *lf = new TLinearFitter(2);
94 // lf->SetFormula("x ++ y ++ x*x*y*y");
95 // --That's the only way to go, if you want to fit in more
96 // than 3 dimensions
97 // 2.2.3 The fastest functions to compute are polynomials and hyperplanes.
98 // --Polynomials are set the usual way: "pol1", "pol2",...
99 // --Hyperplanes are set by expression "hyp3", "hyp4", ...
100 // ---The "hypN" expressions only work when the linear fitter
101 // is used directly, not through TH1::Fit or TGraph::Fit.
102 // To fit a graph or a histogram with a hyperplane, define
103 // the function as "1++x++y".
104 // ---A constant term is assumed for a hyperplane, when using
105 // the "hypN" expression, so "hyp3" is in fact fitting with
106 // "1++x++y++z" function.
107 // --Fitting hyperplanes is much faster than fitting other
108 // expressions so if performance is vital, calculate the
109 // function values beforehand and give them to the fitter
110 // as variables
111 // --Example:
112 // You want to fit "sin(x)|cos(2*x)" very fast. Calculate
113 // sin(x) and cos(2*x) beforehand and store them in array *data.
114 // Then:
115 // TLinearFitter *lf=new TLinearFitter(2, "hyp2");
116 // lf->AssignData(npoint, 2, data, y);
117 //
118 // 2.3 Resetting the formula
119 // 2.3.1 If the input data is stored (or added via AssignData() function),
120 // the fitting formula can be reset without re-adding all the points.
121 // --Example:
122 // TLinearFitter *lf=new TLinearFitter("1++x++x*x");
123 // lf->AssignData(n, 1, x, y, e);
124 // lf->Eval()
125 // //looking at the parameter significance, you see,
126 // // that maybe the fit will improve, if you take out
127 // // the constant term
128 // lf->SetFormula("x++x*x");
129 // lf->Eval();
130 // ...
131 // 2.3.2 If the input data is not stored, the fitter will have to be
132 // cleared and the data will have to be added again to try a
133 // different formula.
134 //
135 // 3.Accessing the fit results
136 // 3.1 There are methods in the fitter to access all relevant information:
137 // --GetParameters, GetCovarianceMatrix, etc
138 // --the t-values of parameters and their significance can be reached by
139 // GetParTValue() and GetParSignificance() methods
140 // 3.2 If fitting with a pre-defined TF123, the fit results are also
141 // written into this function.
142 //
143 //////////////////////////////////////////////////////////////////////////
144 
145 #ifndef ROOT_TVectorD
146 #include "TVectorD.h"
147 #endif
148 #ifndef ROOT_TMatrixD
149 #include "TMatrixD.h"
150 #endif
151 #ifndef ROOT_TFormula
152 #include "TFormula.h"
153 #endif
154 #ifndef ROOT_TVirtualFitter
155 #include "TVirtualFitter.h"
156 #endif
157 
158 
160 
161 private:
162  TVectorD fParams; //vector of parameters
163  TMatrixDSym fParCovar; //matrix of parameters' covariances
164  TVectorD fTValues; //T-Values of parameters
165  TVectorD fParSign; //significance levels of parameters
166  TMatrixDSym fDesign; //matrix AtA
167  TMatrixDSym fDesignTemp; //! temporary matrix, used for num.stability
170 
171  TVectorD fAtb; //vector Atb
172  TVectorD fAtbTemp; //! temporary vector, used for num.stability
175 
176  static std::map<TString,TFormula*> fgFormulaMap; //! map of basis functions and formula
177  TObjArray fFunctions; //array of basis functions
178  TVectorD fY; //the values being fit
179  Double_t fY2; //sum of square of y, used for chisquare
180  Double_t fY2Temp; //! temporary variable used for num.stability
181  TMatrixD fX; //values of x
182  TVectorD fE; //the errors if they are known
183  TFormula *fInputFunction; //the function being fit
184  Double_t fVal[1000]; //! temporary
185 
186  Int_t fNpoints; //number of points
187  Int_t fNfunctions; //number of basis functions
188  Int_t fFormulaSize; //length of the formula
189  Int_t fNdim; //number of dimensions in the formula
190  Int_t fNfixed; //number of fixed parameters
191  Int_t fSpecial; //=100+n if fitting a polynomial of deg.n
192  //=200+n if fitting an n-dimensional hyperplane
193  char *fFormula; //the formula
194  Bool_t fIsSet; //Has the formula been set?
195  Bool_t fStoreData; //Is the data stored?
196  Double_t fChisquare; //Chisquare of the fit
197 
198  Int_t fH; //number of good points in robust fit
199  Bool_t fRobust; //true when performing a robust fit
200  TBits fFitsample; //indices of points, used in the robust fit
201 
202  Bool_t *fFixedParams; //[fNfixed] array of fixed/released params
203 
204 
206  void ComputeTValues();
211 
212  //robust fitting functions:
213  Int_t Partition(Int_t nmini, Int_t *indsubdat);
214  void RDraw(Int_t *subdat, Int_t *indsubdat);
215  void CreateSubset(Int_t ntotal, Int_t h, Int_t *index);
216  Double_t CStep(Int_t step, Int_t h, Double_t *residuals, Int_t *index, Int_t *subdat, Int_t start, Int_t end);
217  Bool_t Linf();
218 
219 public:
220  TLinearFitter();
221  TLinearFitter(Int_t ndim, const char *formula, Option_t *opt="D");
222  TLinearFitter(Int_t ndim);
223  TLinearFitter(TFormula *function, Option_t *opt="D");
224  TLinearFitter(const TLinearFitter& tlf);
225  virtual ~TLinearFitter();
226 
228  virtual void Add(TLinearFitter *tlf);
229  virtual void AddPoint(Double_t *x, Double_t y, Double_t e=1);
230  virtual void AddTempMatrices();
231  virtual void AssignData(Int_t npoints, Int_t xncols, Double_t *x, Double_t *y, Double_t *e=0);
232 
233  virtual void Clear(Option_t *option="");
234  virtual void ClearPoints();
235  virtual void Chisquare();
236  virtual Int_t Eval();
237  virtual Int_t EvalRobust(Double_t h=-1);
238  virtual Int_t ExecuteCommand(const char *command, Double_t *args, Int_t nargs);
239  virtual void FixParameter(Int_t ipar);
240  virtual void FixParameter(Int_t ipar, Double_t parvalue);
241  virtual void GetAtbVector(TVectorD &v);
242  virtual Double_t GetChisquare();
243  virtual void GetConfidenceIntervals(Int_t n, Int_t ndim, const Double_t *x, Double_t *ci, Double_t cl=0.95);
244  virtual void GetConfidenceIntervals(TObject *obj, Double_t cl=0.95);
245  virtual Double_t* GetCovarianceMatrix() const;
246  virtual void GetCovarianceMatrix(TMatrixD &matr);
247  virtual Double_t GetCovarianceMatrixElement(Int_t i, Int_t j) const {return fParCovar(i, j);}
248  virtual void GetDesignMatrix(TMatrixD &matr);
249  virtual void GetErrors(TVectorD &vpar);
250  virtual Int_t GetNumberTotalParameters() const {return fNfunctions;}
251  virtual Int_t GetNumberFreeParameters() const {return fNfunctions-fNfixed;}
252  virtual Int_t GetNpoints() { return fNpoints; }
253  virtual void GetParameters(TVectorD &vpar);
254  virtual Double_t GetParameter(Int_t ipar) const {return fParams(ipar);}
255  virtual Int_t GetParameter(Int_t ipar,char* name,Double_t& value,Double_t& /*verr*/,Double_t& /*vlow*/, Double_t& /*vhigh*/) const;
256  virtual const char *GetParName(Int_t ipar) const;
257  virtual Double_t GetParError(Int_t ipar) const;
258  virtual Double_t GetParTValue(Int_t ipar);
259  virtual Double_t GetParSignificance(Int_t ipar);
260  virtual void GetFitSample(TBits& bits);
261  virtual Double_t GetY2() const {return fY2;}
262  virtual Bool_t IsFixed(Int_t ipar) const {return fFixedParams[ipar];}
263  virtual Int_t Merge(TCollection *list);
264  virtual void PrintResults(Int_t level, Double_t amin=0) const;
265  virtual void ReleaseParameter(Int_t ipar);
266  virtual void SetBasisFunctions(TObjArray * functions);
267  virtual void SetDim(Int_t n);
268  virtual void SetFormula(const char* formula);
269  virtual void SetFormula(TFormula *function);
270  virtual void StoreData(Bool_t store) {fStoreData=store;}
271 
272  virtual Bool_t UpdateMatrix();
273 
274  //dummy functions for TVirtualFitter:
275  virtual Double_t Chisquare(Int_t /*npar*/, Double_t * /*params*/) const {return 0;}
276  virtual Int_t GetErrors(Int_t /*ipar*/,Double_t & /*eplus*/, Double_t & /*eminus*/, Double_t & /*eparab*/, Double_t & /*globcc*/) const {return 0;}
277 
278  virtual Int_t GetStats(Double_t& /*amin*/, Double_t& /*edm*/, Double_t& /*errdef*/, Int_t& /*nvpar*/, Int_t& /*nparx*/) const {return 0;}
279  virtual Double_t GetSumLog(Int_t /*i*/) {return 0;}
280  virtual void SetFitMethod(const char * /*name*/) {;}
281  virtual Int_t SetParameter(Int_t /*ipar*/,const char * /*parname*/,Double_t /*value*/,Double_t /*verr*/,Double_t /*vlow*/, Double_t /*vhigh*/) {return 0;}
282 
283  ClassDef(TLinearFitter, 2) //fit a set of data points with a linear combination of functions
284 };
285 
286 #endif
virtual Bool_t IsFixed(Int_t ipar) const
virtual void GetAtbVector(TVectorD &v)
Get the Atb vector - a vector, used for internal computations.
virtual void GetErrors(TVectorD &vpar)
Returns parameter errors.
virtual void StoreData(Bool_t store)
static std::map< TString, TFormula * > fgFormulaMap
void RDraw(Int_t *subdat, Int_t *indsubdat)
Draws ngroup nonoverlapping subdatasets out of a dataset of size n such that the selected case number...
An array of TObjects.
Definition: TObjArray.h:39
virtual void FixParameter(Int_t ipar)
Fixes paramter #ipar at its current value.
const char Option_t
Definition: RtypesCore.h:62
The Linear Fitter - For fitting functions that are LINEAR IN PARAMETERS.
virtual void AddTempMatrices()
virtual Double_t GetY2() const
TObjArray fFunctions
map of basis functions and formula
virtual void GetConfidenceIntervals(Int_t n, Int_t ndim, const Double_t *x, Double_t *ci, Double_t cl=0.95)
Computes point-by-point confidence intervals for the fitted function Parameters: n - number of points...
TH1 * h
Definition: legend2.C:5
virtual Int_t GetNpoints()
virtual void ClearPoints()
To be used when different sets of points are fitted with the same formula.
Double_t fVal[1000]
virtual Int_t ExecuteCommand(const char *command, Double_t *args, Int_t nargs)
To use in TGraph::Fit and TH1::Fit().
Int_t Graph2DLinearFitter(Double_t h)
Minimisation function for a TGraph2D.
int Int_t
Definition: RtypesCore.h:41
bool Bool_t
Definition: RtypesCore.h:59
virtual void GetDesignMatrix(TMatrixD &matr)
Returns the internal design matrix.
Int_t Partition(Int_t nmini, Int_t *indsubdat)
divides the elements into approximately equal subgroups number of elements in each subgroup is stored...
TFormula * fInputFunction
virtual void PrintResults(Int_t level, Double_t amin=0) const
Level = 3 (to be consistent with minuit) prints parameters and parameter errors.
Double_t fY2Temp
virtual Int_t GetStats(Double_t &, Double_t &, Double_t &, Int_t &, Int_t &) const
Double_t x[n]
Definition: legend1.C:17
#define ClassDef(name, id)
Definition: Rtypes.h:254
Bool_t * fFixedParams
virtual void GetFitSample(TBits &bits)
For robust lts fitting, returns the sample, on which the best fit was based.
virtual Double_t Chisquare(Int_t, Double_t *) const
Double_t CStep(Int_t step, Int_t h, Double_t *residuals, Int_t *index, Int_t *subdat, Int_t start, Int_t end)
The CStep procedure, as described in the article.
virtual void Clear(Option_t *option="")
Clears everything. Used in TH1::Fit and TGraph::Fit().
TMatrixDSym fDesign
virtual void Chisquare()
Calculates the chisquare.
void CreateSubset(Int_t ntotal, Int_t h, Int_t *index)
Creates a p-subset to start ntotal - total number of points from which the subset is chosen...
virtual Double_t GetParTValue(Int_t ipar)
Returns the t-value for parameter #ipar.
virtual Int_t GetErrors(Int_t, Double_t &, Double_t &, Double_t &, Double_t &) const
void AddToDesign(Double_t *x, Double_t y, Double_t e)
Add a point to the AtA matrix and to the Atb vector.
Double_t fChisquare
TVectorD fTValues
TVectorD fAtbTemp
Int_t HistLinearFitter()
Minimization function for H1s using a Chisquare method.
virtual Double_t GetParSignificance(Int_t ipar)
Returns the significance of parameter #ipar.
SVector< double, 2 > v
Definition: Dict.h:5
Int_t MultiGraphLinearFitter(Double_t h)
Minimisation function for a TMultiGraph.
The F O R M U L A class.
Definition: TFormula.h:89
virtual Int_t EvalRobust(Double_t h=-1)
Finds the parameters of the fitted function in case data contains outliers.
Collection abstract base class.
Definition: TCollection.h:48
virtual Double_t GetChisquare()
Get the Chisquare.
virtual Int_t GetNumberFreeParameters() const
Int_t GraphLinearFitter(Double_t h)
Used in TGraph::Fit().
virtual void ReleaseParameter(Int_t ipar)
Releases parameter #ipar.
TLinearFitter()
default c-tor, input data is stored If you don't want to store the input data, run the function Store...
TMatrixD fX
temporary variable used for num.stability
virtual Double_t GetParameter(Int_t ipar) const
virtual void SetBasisFunctions(TObjArray *functions)
set the basis functions in case the fitting function is not set directly The TLinearFitter will manag...
virtual void SetFitMethod(const char *)
virtual Int_t Eval()
Perform the fit and evaluate the parameters Returns 0 if the fit is ok, 1 if there are errors...
TVectorD fAtbTemp3
TMatrixDSym fDesignTemp2
temporary matrix, used for num.stability
virtual void Add(TLinearFitter *tlf)
Add another linear fitter to this linear fitter.
virtual ~TLinearFitter()
Linear fitter cleanup.
double Double_t
Definition: RtypesCore.h:55
TVectorD fParSign
TLinearFitter & operator=(const TLinearFitter &tlf)
Assignment operator.
virtual void GetParameters(TVectorD &vpar)
Returns parameter values.
Double_t y[n]
Definition: legend1.C:17
virtual void AssignData(Int_t npoints, Int_t xncols, Double_t *x, Double_t *y, Double_t *e=0)
This function is to use when you already have all the data in arrays and don't want to copy them into...
virtual void SetFormula(const char *formula)
Additive parts should be separated by "++".
TVectorD fParams
virtual void SetDim(Int_t n)
set the number of dimensions
TMatrixDSym fDesignTemp
void ComputeTValues()
Computes parameters' t-values and significance.
#define name(a, b)
Definition: linkTestLib0.cpp:5
Abstract Base Class for Fitting.
virtual const char * GetParName(Int_t ipar) const
Returns name of parameter #ipar.
Mother of all ROOT objects.
Definition: TObject.h:58
TMatrixDSym fParCovar
Container of bits.
Definition: TBits.h:33
virtual Double_t GetParError(Int_t ipar) const
Returns the error of parameter #ipar.
virtual Int_t SetParameter(Int_t, const char *, Double_t, Double_t, Double_t, Double_t)
virtual Bool_t UpdateMatrix()
Update the design matrix after the formula has been changed.
Int_t fNpoints
temporary
TMatrixDSym fDesignTemp3
virtual Double_t GetSumLog(Int_t)
TObject * obj
TVectorD fAtbTemp2
temporary vector, used for num.stability
float value
Definition: math.cpp:443
virtual Int_t Merge(TCollection *list)
Merge objects in list.
const Int_t n
Definition: legend1.C:16
virtual Double_t * GetCovarianceMatrix() const
Returns covariance matrix.
virtual Int_t GetNumberTotalParameters() const
virtual void AddPoint(Double_t *x, Double_t y, Double_t e=1)
Adds 1 point to the fitter.
virtual Double_t GetCovarianceMatrixElement(Int_t i, Int_t j) const