Logo ROOT   6.07/09
Reference Guide
BinData.h
Go to the documentation of this file.
1 // @(#)root/mathcore:$Id$
2 // Author: L. Moneta Wed Aug 30 11:15:23 2006
3 
4 /**********************************************************************
5  * *
6  * Copyright (c) 2006 LCG ROOT Math Team, CERN/PH-SFT *
7  * *
8  * *
9  **********************************************************************/
10 
11 // Header file for class BinData
12 
13 #ifndef ROOT_Fit_BinData
14 #define ROOT_Fit_BinData
15 
16 #ifndef ROOT_Fit_DataVector
17 #include "Fit/DataVector.h"
18 #endif
19 
20 
21 #ifdef USE_BINPOINT_CLASS
22 
23 #ifndef ROOT_Fit_BinPoint
24 #include "Fit/BinPoint.h"
25 #endif
26 
27 #endif
28 
29 
30 namespace ROOT {
31 
32  namespace Fit {
33 
34 
35 
36 //___________________________________________________________________________________
37 /**
38  Class describing the binned data sets :
39  vectors of x coordinates, y values and optionally error on y values and error on coordinates
40  The dimension of the coordinate is free
41  There are 4 different options:
42  - only coordinates and values (for binned likelihood fits) : kNoError
43  - coordinate, values and error on values (for normal least square fits) : kValueError
44  - coordinate, values, error on values and coordinates (for effective least square fits) : kCoordError
45  - corrdinate, values, error on coordinates and asymmettric error on valyes : kAsymError
46 
47  In addition there is the option to construct Bindata copying the data in (using the DataVector class)
48  or using pointer to external data (DataWrapper) class.
49  In general is found to be more efficient to copy the data.
50  In case of really large data sets for limiting memory consumption then the other option can be used
51  Specialized constructor exists for data up to 3 dimensions.
52 
53  When the data are copying in the number of points can be set later (or re-set) using Initialize and
54  the data are inserted one by one using the Add method.
55  It is mandatory to set the size before using the Add method.
56 
57  @ingroup FitData
58 */
59 
60 
61 class BinData : public FitData {
62 
63 public :
64 
66 
67  static unsigned int GetPointSize(ErrorType err, unsigned int dim) {
68  if (dim == 0 || dim > MaxSize() ) return 0;
69  if (err == kNoError) return dim + 1; // no errors
70  if (err == kValueError) return dim + 2; // error only on the value
71  if (err == kCoordError) return 2 * dim + 2 ; // error on value and coordinate
72  return 2 * dim + 3; // error on value (low and high) and error on coordinate
73  }
74 
76  if (fPointSize == fDim + 1) return kNoError;
77  if (fPointSize == fDim + 2) return kValueError;
78  if (fPointSize == 2 * fDim + 2) return kCoordError;
79  assert( fPointSize == 2 * fDim + 3 ) ;
80  return kAsymError;
81  }
82 
83 
84 
85  /**
86  constructor from dimension of point and max number of points (to pre-allocate vector)
87  Give a zero value and then use Initialize later one if the size is not known
88  */
89 
90  explicit BinData(unsigned int maxpoints = 0, unsigned int dim = 1, ErrorType err = kValueError);
91 
92  /**
93  constructor from option and default range
94  */
95  explicit BinData (const DataOptions & opt, unsigned int maxpoints = 0, unsigned int dim = 1, ErrorType err = kValueError);
96 
97  /**
98  constructor from options and range
99  efault is 1D and value errors
100  */
101  BinData (const DataOptions & opt, const DataRange & range, unsigned int maxpoints = 0, unsigned int dim = 1, ErrorType err = kValueError );
102 
103  /** constructurs using external data */
104 
105  /**
106  constructor from external data for 1D with errors on coordinate and value
107  */
108  BinData(unsigned int n, const double * dataX, const double * val, const double * ex , const double * eval );
109 
110  /**
111  constructor from external data for 2D with errors on coordinate and value
112  */
113  BinData(unsigned int n, const double * dataX, const double * dataY, const double * val, const double * ex , const double * ey, const double * eval );
114 
115  /**
116  constructor from external data for 3D with errors on coordinate and value
117  */
118  BinData(unsigned int n, const double * dataX, const double * dataY, const double * dataZ, const double * val, const double * ex , const double * ey , const double * ez , const double * eval );
119 
120  /**
121  copy constructors
122  */
123  BinData(const BinData &);
124 
125  /**
126  assignment operator
127  */
128  BinData & operator= (const BinData &);
129 
130 
131  /**
132  destructor
133  */
134  virtual ~BinData();
135 
136  /**
137  preallocate a data set with given size , dimension and error type (to get the full point size)
138  If the data set already exists and it is having the compatible point size space for the new points
139  is created in the data sets, while if not compatible the old data are erased and new space of
140  new size is allocated.
141  (i.e if exists initialize is equivalent to a resize( NPoints() + maxpoints)
142  */
143  void Initialize(unsigned int maxpoints, unsigned int dim = 1, ErrorType err = kValueError );
144 
145 
146  /**
147  return the size of a fit point (is the coordinate dimension + 1 for the value and eventually
148  the number of all errors
149  */
150  unsigned int PointSize() const {
151  return fPointSize;
152  }
153 
154  /**
155  return the size of internal data (number of fit points)
156  if data are not copied in but used externally the size is 0
157  */
158  unsigned int DataSize() const {
159  if (fDataVector) return fDataVector->Size();
160  return 0;
161  }
162 
163  /**
164  flag to control if data provides error on the coordinates
165  */
166  bool HaveCoordErrors() const {
167  if (fPointSize > fDim +2) return true;
168  return false;
169  }
170 
171  /**
172  flag to control if data provides asymmetric errors on the value
173  */
174  bool HaveAsymErrors() const {
175  if (fPointSize > 2 * fDim +2) return true;
176  return false;
177  }
178 
179 
180  /**
181  add one dim data with only coordinate and values
182  */
183  void Add(double x, double y );
184 
185  /**
186  add one dim data with no error in the coordinate (x)
187  in this case store the inverse of the error in the value (y)
188  */
189  void Add(double x, double y, double ey);
190 
191  /**
192  add one dim data with error in the coordinate (x)
193  in this case store the value (y) error and not the inverse
194  */
195  void Add(double x, double y, double ex, double ey);
196 
197  /**
198  add one dim data with error in the coordinate (x) and asymmetric errors in the value (y)
199  in this case store the y errors and not the inverse
200  */
201  void Add(double x, double y, double ex, double eyl , double eyh);
202 
203  /**
204  add multi-dim coordinate data with only value (no errors)
205  */
206  void Add(const double *x, double val);
207 
208  /**
209  add multi-dim coordinate data with only error in value
210  */
211  void Add(const double *x, double val, double eval);
212 
213  /**
214  add multi-dim coordinate data with both error in coordinates and value
215  */
216  void Add(const double *x, double val, const double * ex, double eval);
217 
218  /**
219  add multi-dim coordinate data with both error in coordinates and value
220  */
221  void Add(const double *x, double val, const double * ex, double elval, double ehval);
222 
223  /**
224  return a pointer to the coordinates data for the given fit point
225  */
226  const double * Coords(unsigned int ipoint) const {
227  if (fDataVector)
228  return &((fDataVector->Data())[ ipoint*fPointSize ] );
229 
230  return fDataWrapper->Coords(ipoint);
231  }
232 
233  /**
234  return the value for the given fit point
235  */
236  double Value(unsigned int ipoint) const {
237  if (fDataVector)
238  return (fDataVector->Data())[ ipoint*fPointSize + fDim ];
239 
240  return fDataWrapper->Value(ipoint);
241  }
242 
243 
244  /**
245  return error on the value for the given fit point
246  Safe (but slower) method returning correctly the error on the value
247  in case of asymm errors return the average 0.5(eu + el)
248  */
249  double Error(unsigned int ipoint) const {
250  if (fDataVector) {
252  if (type == kNoError ) return 1;
253  // error on the value is the last element in the point structure
254  double eval = (fDataVector->Data())[ (ipoint+1)*fPointSize - 1];
255  if (type == kValueError ) // need to invert (inverror is stored)
256  return eval != 0 ? 1.0/eval : 0;
257  else if (type == kAsymError) { // return 1/2(el + eh)
258  double el = (fDataVector->Data())[ (ipoint+1)*fPointSize - 2];
259  return 0.5 * (el+eval);
260  }
261  return eval; // case of coord errors
262  }
263 
264  return fDataWrapper->Error(ipoint);
265  }
266 
267  /**
268  Return the inverse of error on the value for the given fit point
269  useful when error in the coordinates are not stored and then this is used directly this as the weight in
270  the least square function
271  */
272  double InvError(unsigned int ipoint) const {
273  if (fDataVector) {
274  // error on the value is the last element in the point structure
275  double eval = (fDataVector->Data())[ (ipoint+1)*fPointSize - 1];
276  return eval;
277 // if (!fWithCoordError) return eval;
278 // // when error in the coordinate is stored, need to invert it
279 // return eval != 0 ? 1.0/eval : 0;
280  }
281  //case data wrapper
282 
283  double eval = fDataWrapper->Error(ipoint);
284  return eval != 0 ? 1.0/eval : 0;
285  }
286 
287 
288  /**
289  Return a pointer to the errors in the coordinates for the given fit point
290  */
291  const double * CoordErrors(unsigned int ipoint) const {
292  if (fDataVector) {
293  // error on the value is the last element in the point structure
294  return &(fDataVector->Data())[ (ipoint)*fPointSize + fDim + 1];
295  }
296 
297  return fDataWrapper->CoordErrors(ipoint);
298  }
299 
300  /**
301  retrieve at the same time a pointer to the coordinate data and the fit value
302  More efficient than calling Coords(i) and Value(i)
303  */
304  const double * GetPoint(unsigned int ipoint, double & value) const {
305  if (fDataVector) {
306  unsigned int j = ipoint*fPointSize;
307  const std::vector<double> & v = (fDataVector->Data());
308  const double * x = &v[j];
309  value = v[j+fDim];
310  return x;
311  }
312  value = fDataWrapper->Value(ipoint);
313  return fDataWrapper->Coords(ipoint);
314  }
315 
316  /**
317  retrieve in a single call a pointer to the coordinate data, value and inverse error for
318  the given fit point.
319  To be used only when type is kValueError or kNoError. In the last case the value 1 is returned
320  for the error.
321  */
322  const double * GetPoint(unsigned int ipoint, double & value, double & invError) const {
323  if (fDataVector) {
324  const std::vector<double> & v = (fDataVector->Data());
325  unsigned int j = ipoint*fPointSize;
326  const double * x = &v[j];
327  j += fDim;
328  value = v[j];
329  if (fPointSize == fDim +1) // value error (type=kNoError)
330  invError = 1;
331  else if (fPointSize == fDim +2) // value error (type=kNoError)
332  invError = v[j+1];
333  else
334  assert(0); // cannot be here
335 
336  return x;
337  }
338  value = fDataWrapper->Value(ipoint);
339  double e = fDataWrapper->Error(ipoint);
340  invError = ( e > 0 ) ? 1.0/e : 1.0;
341  return fDataWrapper->Coords(ipoint);
342  }
343 
344  /**
345  Retrieve the errors on the point (coordinate and value) for the given fit point
346  It must be called only when the coordinate errors are stored otherwise it will produce an
347  assert.
348  */
349  const double * GetPointError(unsigned int ipoint, double & errvalue) const {
350  if (fDataVector) {
351  assert(fPointSize > fDim + 2);
352  unsigned int j = ipoint*fPointSize;
353  const std::vector<double> & v = (fDataVector->Data());
354  const double * ex = &v[j+fDim+1];
355  errvalue = v[j + 2*fDim +1];
356  return ex;
357  }
358  errvalue = fDataWrapper->Error(ipoint);
359  return fDataWrapper->CoordErrors(ipoint);
360  }
361 
362  /**
363  Get errors on the point (coordinate errors and asymmetric value errors) for the
364  given fit point.
365  It must be called only when the coordinate errors and asymmetric errors are stored
366  otherwise it will produce an assert.
367  */
368  const double * GetPointError(unsigned int ipoint, double & errlow, double & errhigh) const {
369  // external data is not supported for asymmetric errors
370  assert(fDataVector);
371 
372  assert(fPointSize > 2 * fDim + 2);
373  unsigned int j = ipoint*fPointSize;
374  const std::vector<double> & v = (fDataVector->Data());
375  const double * ex = &v[j+fDim+1];
376  errlow = v[j + 2*fDim +1];
377  errhigh = v[j + 2*fDim +2];
378  return ex;
379  }
380 
381 
382 #ifdef USE_BINPOINT_CLASS
383  const BinPoint & GetPoint(unsigned int ipoint) const {
384  if (fDataVector) {
385  unsigned int j = ipoint*fPointSize;
386  const std::vector<double> & v = (fDataVector->Data());
387  const double * x = &v[j];
388  double value = v[j+fDim];
389  if (fPointSize > fDim + 2) {
390  const double * ex = &v[j+fDim+1];
391  double err = v[j + 2*fDim +1];
392  fPoint.Set(x,value,ex,err);
393  }
394  else {
395  double invError = v[j+fDim+1];
396  fPoint.Set(x,value,invError);
397  }
398 
399  }
400  else {
401  double value = fDataWrapper->Value(ipoint);
402  double e = fDataWrapper->Error(ipoint);
403  if (fPointSize > fDim + 2) {
404  fPoint.Set(fDataWrapper->Coords(ipoint), value, fDataWrapper->CoordErrors(ipoint), e);
405  } else {
406  double invError = ( e != 0 ) ? 1.0/e : 0;
407  fPoint.Set(fDataWrapper->Coords(ipoint), value, invError);
408  }
409  }
410  return fPoint;
411  }
412 
413 
414  const BinPoint & GetPointError(unsigned int ipoint) const {
415  if (fDataVector) {
416  unsigned int j = ipoint*fPointSize;
417  const std::vector<double> & v = (fDataVector->Data());
418  const double * x = &v[j];
419  double value = v[j+fDim];
420  double invError = v[j+fDim+1];
421  fPoint.Set(x,value,invError);
422  }
423  else {
424  double value = fDataWrapper->Value(ipoint);
425  double e = fDataWrapper->Error(ipoint);
426  double invError = ( e != 0 ) ? 1.0/e : 0;
427  fPoint.Set(fDataWrapper->Coords(ipoint), value, invError);
428  }
429  return fPoint;
430  }
431 #endif
432 
433  /**
434  resize the vector to the new given npoints
435  if vector does not exists is created using existing point size
436  */
437  void Resize (unsigned int npoints);
438 
439  /**
440  return number of fit points
441  */
442  unsigned int NPoints() const { return fNPoints; }
443 
444  /**
445  return number of fit points
446  */
447  unsigned int Size() const { return fNPoints; }
448 
449  /**
450  return coordinate data dimension
451  */
452  unsigned int NDim() const { return fDim; }
453 
454  /**
455  apply a Log transformation of the data values
456  can be used for example when fitting an exponential or gaussian
457  Transform the data in place need to copy if want to preserve original data
458  The data sets must not contain negative values. IN case it does,
459  an empty data set is returned
460  */
461  BinData & LogTransform();
462 
463 
464  /**
465  return an array containing the upper edge of the bin for coordinate i
466  In case of empty bin they could be merged in a single larger bin
467  Return a NULL pointer if the bin width is not stored
468  */
469  const double * BinUpEdge(unsigned int icoord) const {
470  if (fBinEdge.size() == 0 || icoord*fDim > fBinEdge.size() ) return 0;
471  return &fBinEdge[ icoord * fDim];
472  }
473 
474  /**
475  query if the data store the bin edges instead of the center
476  */
477  bool HasBinEdges() const {
478  return fBinEdge.size() > 0 && fBinEdge.size() == fDim*fNPoints;
479  }
480 
481  /**
482  add the bin width data, a pointer to an array with the bin upper edge information.
483  This is needed when fitting with integral options
484  The information is added for the previously inserted point.
485  BinData::Add must be called before
486  */
487  void AddBinUpEdge(const double * xup);
488 
489  /**
490  retrieve the reference volume used to normalize the data when the option bin volume is set
491  */
492  double RefVolume() const { return fRefVolume; }
493 
494  /**
495  set the reference volume used to normalize the data when the option bin volume is set
496  */
497  void SetRefVolume(double value) { fRefVolume = value; }
498 
499 
500  /**
501  compute the total sum of the data content
502  (sum of weights in cse of weighted data set)
503  */
504  double SumOfContent() const { return fSumContent; }
505 
506  /**
507  compute the total sum of the error square
508  (sum of weight square in case of a weighted data set)
509  */
510  double SumOfError2() const { return fSumError2;}
511 
512 
513 protected:
514 
515  void SetNPoints(unsigned int n) { fNPoints = n; }
516 
517 private:
518 
519 
520  unsigned int fDim; // coordinate dimension
521  unsigned int fPointSize; // total point size including value and errors (= fDim + 2 for error in only Y )
522  unsigned int fNPoints; // number of contained points in the data set (can be different than size of vector)
523  double fSumContent; // total sum of the bin data content
524  double fSumError2; // total sum square of the errors
525  double fRefVolume; // reference bin volume - used to normalize the bins in case of variable bins data
526 
527  DataVector * fDataVector; // pointer to the copied in data vector
528  DataWrapper * fDataWrapper; // pointer to the external data wrapper structure
529 
530  std::vector<double> fBinEdge; // vector containing the bin upper edge (coordinate will contain low edge)
531 
532 
533 #ifdef USE_BINPOINT_CLASS
534  mutable BinPoint fPoint;
535 #endif
536 
537 };
538 
539 
540  } // end namespace Fit
541 
542 } // end namespace ROOT
543 
544 
545 
546 #endif /* ROOT_Fit_BinData */
547 
548 
ErrorType GetErrorType() const
Definition: BinData.h:75
void Initialize(unsigned int maxpoints, unsigned int dim=1, ErrorType err=kValueError)
preallocate a data set with given size , dimension and error type (to get the full point size) If the...
Definition: BinData.cxx:216
This namespace contains pre-defined functions to be used in conjuction with TExecutor::Map and TExecu...
Definition: StringConv.hxx:21
double RefVolume() const
retrieve the reference volume used to normalize the data when the option bin volume is set ...
Definition: BinData.h:492
double Value(unsigned int ipoint) const
Definition: DataVector.h:363
void SetNPoints(unsigned int n)
Definition: BinData.h:515
Base class for all the fit data types.
Definition: DataVector.h:67
const double * Coords(unsigned int ipoint) const
Definition: DataVector.h:332
void AddBinUpEdge(const double *xup)
add the bin width data, a pointer to an array with the bin upper edge information.
Definition: BinData.cxx:452
DataWrapper * fDataWrapper
Definition: BinData.h:528
BinData & operator=(const BinData &)
assignment operator
Definition: BinData.cxx:174
bool HaveAsymErrors() const
flag to control if data provides asymmetric errors on the value
Definition: BinData.h:174
unsigned int Size() const
return number of fit points
Definition: BinData.h:447
double SumOfError2() const
compute the total sum of the error square (sum of weight square in case of a weighted data set) ...
Definition: BinData.h:510
const FData & Data() const
const access to underlying vector
Definition: DataVector.h:163
const double * BinUpEdge(unsigned int icoord) const
return an array containing the upper edge of the bin for coordinate i In case of empty bin they could...
Definition: BinData.h:469
unsigned int fDim
Definition: BinData.h:520
Double_t x[n]
Definition: legend1.C:17
Obsolete class, no more in use.
Definition: BinPoint.h:33
class holding the fit data points.
Definition: DataVector.h:134
const double * CoordErrors(unsigned int ipoint) const
Definition: DataVector.h:348
unsigned int PointSize() const
return the size of a fit point (is the coordinate dimension + 1 for the value and eventually the numb...
Definition: BinData.h:150
DataVector * fDataVector
Definition: BinData.h:527
double fSumError2
Definition: BinData.h:524
double fSumContent
Definition: BinData.h:523
double SumOfContent() const
compute the total sum of the data content (sum of weights in cse of weighted data set) ...
Definition: BinData.h:504
unsigned int DataSize() const
return the size of internal data (number of fit points) if data are not copied in but used externally...
Definition: BinData.h:158
class maintaining a pointer to external data Using this class avoids copying the data when performing...
Definition: DataVector.h:222
DataOptions : simple structure holding the options on how the data are filled.
Definition: DataOptions.h:28
SVector< double, 2 > v
Definition: Dict.h:5
double fRefVolume
Definition: BinData.h:525
const double * Coords(unsigned int ipoint) const
return a pointer to the coordinates data for the given fit point
Definition: BinData.h:226
virtual ~BinData()
destructor
Definition: BinData.cxx:210
Class describing the binned data sets : vectors of x coordinates, y values and optionally error on y ...
Definition: BinData.h:61
void SetRefVolume(double value)
set the reference volume used to normalize the data when the option bin volume is set ...
Definition: BinData.h:497
double InvError(unsigned int ipoint) const
Return the inverse of error on the value for the given fit point useful when error in the coordinates...
Definition: BinData.h:272
void Resize(unsigned int npoints)
resize the vector to the new given npoints if vector does not exists is created using existing point ...
Definition: BinData.cxx:246
BinData(unsigned int maxpoints=0, unsigned int dim=1, ErrorType err=kValueError)
constructor from dimension of point and max number of points (to pre-allocate vector) Give a zero val...
Definition: BinData.cxx:28
unsigned int NPoints() const
return number of fit points
Definition: BinData.h:442
class describing the range in the coordinates it supports multiple range in a coordinate.
Definition: DataRange.h:34
void Add(double x, double y)
add one dim data with only coordinate and values
Definition: BinData.cxx:265
TFitResultPtr Fit(FitObject *h1, TF1 *f1, Foption_t &option, const ROOT::Math::MinimizerOptions &moption, const char *goption, ROOT::Fit::DataRange &range)
Definition: HFitImpl.cxx:134
int type
Definition: TGX11.cxx:120
Double_t y[n]
Definition: legend1.C:17
Double_t ey[n]
Definition: legend1.C:17
you should not use this method at all Int_t Int_t Double_t Double_t Double_t e
Definition: TRolke.cxx:630
const double * GetPointError(unsigned int ipoint, double &errlow, double &errhigh) const
Get errors on the point (coordinate errors and asymmetric value errors) for the given fit point...
Definition: BinData.h:368
BinData & LogTransform()
apply a Log transformation of the data values can be used for example when fitting an exponential or ...
Definition: BinData.cxx:480
double Error(unsigned int ipoint) const
return error on the value for the given fit point Safe (but slower) method returning correctly the er...
Definition: BinData.h:249
double Value(unsigned int ipoint) const
return the value for the given fit point
Definition: BinData.h:236
bool HasBinEdges() const
query if the data store the bin edges instead of the center
Definition: BinData.h:477
size_t Size() const
full size of data vector (npoints * point size)
Definition: DataVector.h:197
unsigned int fPointSize
Definition: BinData.h:521
double Error(unsigned int ipoint) const
Definition: DataVector.h:367
static unsigned int MaxSize()
define a max size to avoid allocating too large arrays
Definition: DataVector.h:111
const double * CoordErrors(unsigned int ipoint) const
Return a pointer to the errors in the coordinates for the given fit point.
Definition: BinData.h:291
const double * GetPoint(unsigned int ipoint, double &value) const
retrieve at the same time a pointer to the coordinate data and the fit value More efficient than call...
Definition: BinData.h:304
static unsigned int GetPointSize(ErrorType err, unsigned int dim)
Definition: BinData.h:67
bool HaveCoordErrors() const
flag to control if data provides error on the coordinates
Definition: BinData.h:166
Double_t ex[n]
Definition: legend1.C:17
const Int_t n
Definition: legend1.C:16
unsigned int fNPoints
Definition: BinData.h:522
const double * GetPoint(unsigned int ipoint, double &value, double &invError) const
retrieve in a single call a pointer to the coordinate data, value and inverse error for the given fit...
Definition: BinData.h:322
unsigned int NDim() const
return coordinate data dimension
Definition: BinData.h:452
std::vector< double > fBinEdge
Definition: BinData.h:530
const double * GetPointError(unsigned int ipoint, double &errvalue) const
Retrieve the errors on the point (coordinate and value) for the given fit point It must be called onl...
Definition: BinData.h:349