YODA is hosted by Hepforge, IPPP Durham
YODA::Dbn1D Class Reference

A 1D distribution. More...

#include <Dbn1D.h>

Public Member Functions

Constructors
 Dbn1D ()
 Default constructor of a new distribution. More...
 
 Dbn1D (unsigned long numEntries, double sumW, double sumW2, double sumWX, double sumWX2)
 Constructor to set a distribution with a pre-filled state. More...
 
 Dbn1D (const Dbn1D &toCopy)
 
Dbn1Doperator= (const Dbn1D &toCopy)
 
Modifiers
void fill (double val, double weight=1.0)
 Contribute a sample at val with weight weight. More...
 
void reset ()
 Reset the internal counters. More...
 
void scaleW (double scalefactor)
 Rescale as if all fill weights had been different by factor scalefactor. More...
 
void scaleX (double factor)
 Rescale x: needed if histo bin edges are rescaled. More...
 
Distribution statistics
double errW () const
 The absolute error on sumW. More...
 
double relErrW () const
 The relative error on sumW. More...
 
double xMean () const
 Weighted mean, $ \bar{x} $, of distribution. More...
 
double xVariance () const
 Weighted variance, $ \sigma^2 $, of distribution. More...
 
double xStdDev () const
 Weighted standard deviation, $ \sigma $, of distribution. More...
 
double xStdErr () const
 Weighted standard error on the mean, $ \sim \sigma/\sqrt{N-1} $, of distribution. More...
 
double xRMS () const
 Weighted RMS, $ \sqrt{ \sum{w x^2}/\sum{w} } $, of distribution. More...
 
Raw distribution running sums
unsigned long numEntries () const
 Number of entries (number of times fill was called, ignoring weights) More...
 
double effNumEntries () const
 Effective number of entries $ = (\sum w)^2 / \sum w^2 $. More...
 
double sumW () const
 The sum of weights. More...
 
double sumW2 () const
 The sum of weights squared. More...
 
double sumWX () const
 The sum of x*weight. More...
 
double sumWX2 () const
 The sum of x^2*weight. More...
 
Operators
Dbn1Doperator+= (const Dbn1D &d)
 Add two dbns. More...
 
Dbn1Doperator-= (const Dbn1D &d)
 Subtract one dbn from another. More...
 

Protected Member Functions

Dbn1Dadd (const Dbn1D &d)
 Add two dbns (internal, explicitly named version) More...
 
Dbn1Dsubtract (const Dbn1D &d)
 Subtract one dbn from another (internal, explicitly named version) More...
 

Detailed Description

A 1D distribution.

This class is used internally by YODA to centralise the calculation of statistics of unbounded, unbinned sampled distributions. Each distribution fill contributes a weight, $ w $, and a value, $ x $. By storing the total number of fills (ignoring weights), $ \sum w $, $ \sum w^2 $, $ \sum wx $, and $ \sum wx^2 $, the Dbn1D can calculate the mean and spread ( $ \sigma^2 $, $ \sigma $ and $ \hat{\sigma} $) of the sampled distribution. It is used to provide this information in bins and for the "hidden" $ y $ distribution in profile histogram bins.

Definition at line 28 of file Dbn1D.h.

Constructor & Destructor Documentation

YODA::Dbn1D::Dbn1D ( )
inline

Default constructor of a new distribution.

Definition at line 35 of file Dbn1D.h.

References reset().

35  {
36  reset();
37  }
void reset()
Reset the internal counters.
Definition: Dbn1D.h:85
YODA::Dbn1D::Dbn1D ( unsigned long  numEntries,
double  sumW,
double  sumW2,
double  sumWX,
double  sumWX2 
)
inline

Constructor to set a distribution with a pre-filled state.

Principally designed for internal persistency use.

Definition at line 43 of file Dbn1D.h.

44  : _dbnW(numEntries, sumW, sumW2),
45  _sumWX(sumWX),
46  _sumWX2(sumWX2)
47  { }
double sumW() const
The sum of weights.
Definition: Dbn1D.h:152
double sumWX2() const
The sum of x^2*weight.
Definition: Dbn1D.h:167
double sumW2() const
The sum of weights squared.
Definition: Dbn1D.h:157
double sumWX() const
The sum of x*weight.
Definition: Dbn1D.h:162
unsigned long numEntries() const
Number of entries (number of times fill was called, ignoring weights)
Definition: Dbn1D.h:142
YODA::Dbn1D::Dbn1D ( const Dbn1D toCopy)
inline

Copy constructor

Sets all the parameters using the ones provided from an existing Dbn1D.

Definition at line 53 of file Dbn1D.h.

53  {
54  _dbnW = toCopy._dbnW;
55  _sumWX = toCopy._sumWX;
56  _sumWX2 = toCopy._sumWX2;
57  }

Member Function Documentation

Dbn1D & YODA::Dbn1D::add ( const Dbn1D d)
protected

Add two dbns (internal, explicitly named version)

Definition at line 70 of file Dbn1D.cc.

Referenced by operator+=().

70  {
71  _dbnW += d._dbnW;
72  _sumWX += d._sumWX;
73  _sumWX2 += d._sumWX2;
74  return *this;
75  }
double YODA::Dbn1D::effNumEntries ( ) const
inline

Effective number of entries $ = (\sum w)^2 / \sum w^2 $.

Definition at line 147 of file Dbn1D.h.

Referenced by YODA::Histo1D::effNumEntries(), YODA::WriterYODA::writeHisto1D(), xMean(), xRMS(), xStdErr(), and xVariance().

147  {
148  return _dbnW.effNumEntries();
149  }
double YODA::Dbn1D::errW ( ) const
inline

The absolute error on sumW.

Definition at line 115 of file Dbn1D.h.

115 { return _dbnW.errW(); }
void YODA::Dbn1D::fill ( double  val,
double  weight = 1.0 
)
inline

Contribute a sample at val with weight weight.

Definition at line 77 of file Dbn1D.h.

77  {
78  _dbnW.fill(weight);
79  _sumWX += weight*val;
80  _sumWX2 += weight*val*val;
81  }
unsigned long YODA::Dbn1D::numEntries ( ) const
inline

Number of entries (number of times fill was called, ignoring weights)

Definition at line 142 of file Dbn1D.h.

Referenced by YODA::Histo1D::numEntries(), and YODA::WriterYODA::writeHisto1D().

142  {
143  return _dbnW.numEntries();
144  }
Dbn1D& YODA::Dbn1D::operator+= ( const Dbn1D d)
inline

Add two dbns.

Definition at line 178 of file Dbn1D.h.

References add().

178  {
179  return add(d);
180  }
Dbn1D & add(const Dbn1D &d)
Add two dbns (internal, explicitly named version)
Definition: Dbn1D.cc:70
Dbn1D& YODA::Dbn1D::operator-= ( const Dbn1D d)
inline

Subtract one dbn from another.

Definition at line 183 of file Dbn1D.h.

References subtract().

183  {
184  return subtract(d);
185  }
Dbn1D & subtract(const Dbn1D &d)
Subtract one dbn from another (internal, explicitly named version)
Definition: Dbn1D.cc:78
Dbn1D& YODA::Dbn1D::operator= ( const Dbn1D toCopy)
inline

Copy assignment

Sets all the parameters using the ones provided from an existing Dbn1D.

Definition at line 63 of file Dbn1D.h.

63  {
64  _dbnW = toCopy._dbnW;
65  _sumWX = toCopy._sumWX;
66  _sumWX2 = toCopy._sumWX2;
67  return *this;
68  }
double YODA::Dbn1D::relErrW ( ) const
inline

The relative error on sumW.

Definition at line 118 of file Dbn1D.h.

118 { return _dbnW.relErrW(); }
void YODA::Dbn1D::reset ( )
inline

Reset the internal counters.

Definition at line 85 of file Dbn1D.h.

Referenced by Dbn1D().

85  {
86  _dbnW.reset();
87  _sumWX = 0;
88  _sumWX2 = 0;
89  }
void YODA::Dbn1D::scaleW ( double  scalefactor)
inline

Rescale as if all fill weights had been different by factor scalefactor.

Definition at line 93 of file Dbn1D.h.

93  {
94  _dbnW.scaleW(scalefactor);
95  _sumWX *= scalefactor;
96  _sumWX2 *= scalefactor;
97  }
void YODA::Dbn1D::scaleX ( double  factor)
inline

Rescale x: needed if histo bin edges are rescaled.

Definition at line 101 of file Dbn1D.h.

101  {
102  _sumWX *= factor;
103  _sumWX2 *= factor*factor;
104  }
Dbn1D & YODA::Dbn1D::subtract ( const Dbn1D d)
protected

Subtract one dbn from another (internal, explicitly named version)

Definition at line 78 of file Dbn1D.cc.

Referenced by operator-=().

78  {
79  _dbnW -= d._dbnW;
80  _sumWX -= d._sumWX;
81  _sumWX2 -= d._sumWX2;
82  return *this;
83  }
double YODA::Dbn1D::sumW ( ) const
inline

The sum of weights.

Definition at line 152 of file Dbn1D.h.

Referenced by YODA::Histo1D::integral(), YODA::toIntegralEfficiencyHisto(), YODA::toIntegralHisto(), YODA::toTH1D(), YODA::WriterYODA::writeHisto1D(), xMean(), xRMS(), and xVariance().

152  {
153  return _dbnW.sumW();
154  }
double YODA::Dbn1D::sumW2 ( ) const
inline

The sum of weights squared.

Definition at line 157 of file Dbn1D.h.

Referenced by YODA::toTH1D(), YODA::WriterYODA::writeHisto1D(), and xVariance().

157  {
158  return _dbnW.sumW2();
159  }
double YODA::Dbn1D::sumWX ( ) const
inline

The sum of x*weight.

Definition at line 162 of file Dbn1D.h.

Referenced by YODA::WriterYODA::writeHisto1D(), xMean(), and xVariance().

162  {
163  return _sumWX;
164  }
double YODA::Dbn1D::sumWX2 ( ) const
inline

The sum of x^2*weight.

Definition at line 167 of file Dbn1D.h.

Referenced by YODA::WriterYODA::writeHisto1D(), xRMS(), and xVariance().

167  {
168  return _sumWX2;
169  }
double YODA::Dbn1D::xMean ( ) const

Weighted mean, $ \bar{x} $, of distribution.

Definition at line 11 of file Dbn1D.cc.

References effNumEntries(), sumW(), and sumWX().

11  {
12  if (effNumEntries() == 0 || sumW() == 0) {
13  throw LowStatsError("Requested mean of a distribution with no net fill weights");
14  }
15  // This is ok, even for negative sum(w)
16  return sumWX()/sumW();
17  }
double sumW() const
The sum of weights.
Definition: Dbn1D.h:152
double effNumEntries() const
Effective number of entries .
Definition: Dbn1D.h:147
double sumWX() const
The sum of x*weight.
Definition: Dbn1D.h:162
double YODA::Dbn1D::xRMS ( ) const

Weighted RMS, $ \sqrt{ \sum{w x^2}/\sum{w} } $, of distribution.

Definition at line 59 of file Dbn1D.cc.

References effNumEntries(), sumW(), and sumWX2().

59  {
60  // Weighted RMS defined as
61  // rms = sqrt(sum{w x^2} / sum{w})
62  if (effNumEntries() == 0) {
63  throw LowStatsError("Requested RMS of a distribution with no net fill weights");
64  }
65  const double meansq = sumWX2() / sumW();
66  return std::sqrt(meansq);
67  }
double sumW() const
The sum of weights.
Definition: Dbn1D.h:152
double sumWX2() const
The sum of x^2*weight.
Definition: Dbn1D.h:167
double effNumEntries() const
Effective number of entries .
Definition: Dbn1D.h:147
double YODA::Dbn1D::xStdDev ( ) const
inline

Weighted standard deviation, $ \sigma $, of distribution.

Definition at line 127 of file Dbn1D.h.

References xVariance().

127 { return std::sqrt(xVariance()); }
double xVariance() const
Weighted variance, , of distribution.
Definition: Dbn1D.cc:20
double YODA::Dbn1D::xStdErr ( ) const

Weighted standard error on the mean, $ \sim \sigma/\sqrt{N-1} $, of distribution.

Todo:
Unbiased should check that Neff > 1 and divide by N-1?

Definition at line 49 of file Dbn1D.cc.

References effNumEntries(), and xVariance().

49  {
50  // Handle zero/negative sum weight
51  if (effNumEntries() == 0) {
52  throw LowStatsError("Requested std error of a distribution with no net fill weights");
53  }
55  return std::sqrt(xVariance() / effNumEntries());
56  }
double xVariance() const
Weighted variance, , of distribution.
Definition: Dbn1D.cc:20
double effNumEntries() const
Effective number of entries .
Definition: Dbn1D.h:147
double YODA::Dbn1D::xVariance ( ) const

Weighted variance, $ \sigma^2 $, of distribution.

Todo:
Isn't this sensitive to the overall scale of the weights? Shouldn't it check if den is bigger then num by a set number of orders of magnitude and vice versa?

We take the modulus of the weighted variance since the expression above can be negative with weighted means

Todo:
Is this the correct approach? There is no information online other than "weights are non-negative"...

Definition at line 20 of file Dbn1D.cc.

References effNumEntries(), YODA::fuzzyLessEquals(), YODA::sqr(), sumW(), sumW2(), sumWX(), and sumWX2().

Referenced by xStdDev(), and xStdErr().

20  {
21  // Weighted variance defined as
22  // sig2 = ( sum(wx**2) * sum(w) - sum(wx)**2 ) / ( sum(w)**2 - sum(w**2) )
23  // see http://en.wikipedia.org/wiki/Weighted_mean
24  if (effNumEntries() == 0) {
25  throw LowStatsError("Requested variance of a distribution with no net fill weights");
26  } else if (fuzzyLessEquals(effNumEntries(), 1.0)) {
27  throw LowStatsError("Requested variance of a distribution with only one effective entry");
28  }
29  const double num = sumWX2()*sumW() - sqr(sumWX());
30  const double den = sqr(sumW()) - sumW2();
31  if (den==0.) {
32  std::cerr << "testing is this the problem ??? " << num << " " << den << "\n";
33  throw WeightError("Undefined weighted variance");
34  }
38  // if (fabs(num) < 1e-10 && fabs(den) < 1e-10) {
39  // throw WeightError("Numerically unstable weights in width calculation");
40  // }
41  // The weighted variance as defined above
42  const double var = num/den;
45  return fabs(var);
46  }
double sumW() const
The sum of weights.
Definition: Dbn1D.h:152
double sumWX2() const
The sum of x^2*weight.
Definition: Dbn1D.h:167
double effNumEntries() const
Effective number of entries .
Definition: Dbn1D.h:147
double sumW2() const
The sum of weights squared.
Definition: Dbn1D.h:157
double sumWX() const
The sum of x*weight.
Definition: Dbn1D.h:162
NUM sqr(NUM a)
Named number-type squaring operation.
Definition: MathUtils.h:203
bool fuzzyLessEquals(double a, double b, double tolerance=1E-5)
Compare two floating point numbers for <= with a degree of fuzziness.
Definition: MathUtils.h:111

The documentation for this class was generated from the following files: