OpenVDB  11.0.0
Stats.h
Go to the documentation of this file.
1 // Copyright Contributors to the OpenVDB Project
2 // SPDX-License-Identifier: MPL-2.0
3 //
4 /// @file Stats.h
5 ///
6 /// @author Ken Museth
7 ///
8 /// @brief Classes to compute statistics and histograms
9 
10 #ifndef OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
11 #define OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
12 
13 #include <iosfwd> // for ostringstream
14 #include <openvdb/version.h>
15 #include <openvdb/Exceptions.h>
16 #include <iostream>
17 #include <iomanip>
18 #include <sstream>
19 #include <vector>
20 #include <functional>// for std::less
21 #include "Math.h"
22 
23 namespace openvdb {
25 namespace OPENVDB_VERSION_NAME {
26 namespace math {
27 
28 /// @brief Templated class to compute the minimum and maximum values.
29 template <typename ValueType, typename Less = std::less<ValueType> >
30 class MinMax
31 {
32  using Limits = std::numeric_limits<ValueType>;
33 public:
34 
35  /// @brief Empty constructor
36  ///
37  /// @warning Only use this constructor with POD types
38  MinMax() : mMin(Limits::max()), mMax(Limits::lowest())
39  {
40  static_assert(std::numeric_limits<ValueType>::is_specialized,
41  "openvdb::math::MinMax default constructor requires a std::numeric_limits specialization");
42  }
43 
44  /// @brief Constructor
45  MinMax(const ValueType &min, const ValueType &max)
46  : mMin(min), mMax(max) {}
47 
48  /// Add a single sample.
49  inline void add(const ValueType &val, const Less &less = Less())
50  {
51  if (less(val, mMin)) mMin = val;
52  if (less(mMax, val)) mMax = val;
53  }
54 
55  /// Return the minimum value.
56  inline const ValueType& min() const { return mMin; }
57 
58  /// Return the maximum value.
59  inline const ValueType& max() const { return mMax; }
60 
61  /// Add the samples from the other Stats instance.
62  inline void add(const MinMax& other, const Less &less = Less())
63  {
64  if (less(other.mMin, mMin)) mMin = other.mMin;
65  if (less(mMax, other.mMax)) mMax = other.mMax;
66  }
67 
68  /// @brief Print MinMax to the specified output stream.
69  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
70  {
71  // Write to a temporary string stream so as not to affect the state
72  // (precision, field width, etc.) of the output stream.
73  std::ostringstream os;
74  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
75  os << "MinMax ";
76  if (!name.empty()) os << "for \"" << name << "\" ";
77  os << " Min=" << mMin << ", Max=" << mMax << std::endl;
78  strm << os.str();
79  }
80 
81 protected:
82 
83  ValueType mMin, mMax;
84 };//end MinMax
85 
86 /// @brief This class computes the minimum and maximum values of a population
87 /// of floating-point values.
88 class Extrema
89 {
90 public:
91 
92  /// @brief Constructor
93  /// @warning The min/max values are initiated to extreme values
95  : mSize(0)
96  , mMin(std::numeric_limits<double>::max())
97  , mMax(-mMin)
98  {
99  }
100 
101  /// Add a single sample.
102  void add(double val)
103  {
104  ++mSize;
105  mMin = std::min<double>(val, mMin);
106  mMax = std::max<double>(val, mMax);
107  }
108 
109  /// Add @a n samples with constant value @a val.
110  void add(double val, uint64_t n)
111  {
112  mSize += n;
113  mMin = std::min<double>(val, mMin);
114  mMax = std::max<double>(val, mMax);
115  }
116 
117  /// Return the size of the population, i.e., the total number of samples.
118  inline uint64_t size() const { return mSize; }
119 
120  /// Return the minimum value.
121  inline double min() const { return mMin; }
122 
123  /// Return the maximum value.
124  inline double max() const { return mMax; }
125 
126  /// Return the range defined as the maximum value minus the minimum value.
127  inline double range() const { return mMax - mMin; }
128 
129  /// Add the samples from the other Stats instance.
130  void add(const Extrema& other)
131  {
132  if (other.mSize > 0) this->join(other);
133  }
134 
135  /// @brief Print extrema to the specified output stream.
136  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
137  {
138  // Write to a temporary string stream so as not to affect the state
139  // (precision, field width, etc.) of the output stream.
140  std::ostringstream os;
141  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
142  os << "Extrema ";
143  if (!name.empty()) os << "for \"" << name << "\" ";
144  if (mSize>0) {
145  os << "with " << mSize << " samples:\n"
146  << " Min=" << mMin
147  << ", Max=" << mMax
148  << ", Range="<< this->range() << std::endl;
149  } else {
150  os << ": no samples were added." << std::endl;
151  }
152  strm << os.str();
153  }
154 
155 protected:
156 
157  inline void join(const Extrema& other)
158  {
159  assert(other.mSize > 0);
160  mSize += other.mSize;
161  mMin = std::min<double>(mMin, other.mMin);
162  mMax = std::max<double>(mMax, other.mMax);
163  }
164 
165  uint64_t mSize;
166  double mMin, mMax;
167 };//end Extrema
168 
169 
170 /// @brief This class computes statistics (minimum value, maximum
171 /// value, mean, variance and standard deviation) of a population
172 /// of floating-point values.
173 ///
174 /// @details variance = Mean[ (X-Mean[X])^2 ] = Mean[X^2] - Mean[X]^2,
175 /// standard deviation = sqrt(variance)
176 ///
177 /// @note This class employs incremental computation and double precision.
178 class Stats : public Extrema
179 {
180 public:
182  : Extrema()
183  , mAvg(0.0)
184  , mAux(0.0)
185  {
186  }
187 
188  /// Add a single sample.
189  void add(double val)
190  {
191  Extrema::add(val);
192  const double delta = val - mAvg;
193  mAvg += delta/double(mSize);
194  mAux += delta*(val - mAvg);
195  }
196 
197  /// Add @a n samples with constant value @a val.
198  void add(double val, uint64_t n)
199  {
200  const double denom = 1.0/double(mSize + n);
201  const double delta = val - mAvg;
202  mAvg += denom * delta * double(n);
203  mAux += denom * delta * delta * double(mSize) * double(n);
204  Extrema::add(val, n);
205  }
206 
207  /// Add the samples from the other Stats instance.
208  void add(const Stats& other)
209  {
210  if (other.mSize > 0) {
211  const double denom = 1.0/double(mSize + other.mSize);
212  const double delta = other.mAvg - mAvg;
213  mAvg += denom * delta * double(other.mSize);
214  mAux += other.mAux + denom * delta * delta * double(mSize) * double(other.mSize);
215  Extrema::join(other);
216  }
217  }
218 
219  //@{
220  /// Return the arithmetic mean, i.e. average, value.
221  inline double avg() const { return mAvg; }
222  inline double mean() const { return mAvg; }
223  //@}
224 
225  //@{
226  /// @brief Return the population variance.
227  /// @note The unbiased sample variance = population variance *
228  //num/(num-1)
229  inline double var() const { return mSize<2 ? 0.0 : mAux/double(mSize); }
230  inline double variance() const { return this->var(); }
231  //@}
232 
233  //@{
234  /// @brief Return the standard deviation (=Sqrt(variance)) as
235  /// defined from the (biased) population variance.
236  inline double std() const { return sqrt(this->var()); }
237  inline double stdDev() const { return this->std(); }
238  //@}
239 
240  /// @brief Print statistics to the specified output stream.
241  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
242  {
243  // Write to a temporary string stream so as not to affect the state
244  // (precision, field width, etc.) of the output stream.
245  std::ostringstream os;
246  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
247  os << "Statistics ";
248  if (!name.empty()) os << "for \"" << name << "\" ";
249  if (mSize>0) {
250  os << "with " << mSize << " samples:\n"
251  << " Min=" << mMin
252  << ", Max=" << mMax
253  << ", Ave=" << mAvg
254  << ", Std=" << this->stdDev()
255  << ", Var=" << this->variance() << std::endl;
256  } else {
257  os << ": no samples were added." << std::endl;
258  }
259  strm << os.str();
260  }
261 
262 protected:
263  using Extrema::mSize;
264  using Extrema::mMin;
265  using Extrema::mMax;
266  double mAvg, mAux;
267 }; // end Stats
268 
269 
270 ////////////////////////////////////////
271 
272 
273 /// @brief This class computes a histogram, with a fixed interval width,
274 /// of a population of floating-point values.
276 {
277 public:
278  /// Construct with given minimum and maximum values and the given bin count.
279  Histogram(double min, double max, size_t numBins = 10)
280  : mSize(0), mMin(min), mMax(max + 1e-10),
281  mDelta(double(numBins)/(max-min)), mBins(numBins)
282  {
283  if ( mMax <= mMin ) {
284  OPENVDB_THROW(ValueError, "Histogram: expected min < max");
285  } else if ( numBins == 0 ) {
286  OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
287  }
288  for (size_t i=0; i<numBins; ++i) mBins[i]=0;
289  }
290 
291  /// @brief Construct with the given bin count and with minimum and maximum values
292  /// taken from a Stats object.
293  Histogram(const Stats& s, size_t numBins = 10):
294  mSize(0), mMin(s.min()), mMax(s.max()+1e-10),
295  mDelta(double(numBins)/(mMax-mMin)), mBins(numBins)
296  {
297  if ( mMax <= mMin ) {
298  OPENVDB_THROW(ValueError, "Histogram: expected min < max");
299  } else if ( numBins == 0 ) {
300  OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
301  }
302  for (size_t i=0; i<numBins; ++i) mBins[i]=0;
303  }
304 
305  /// @brief Add @a n samples with constant value @a val, provided that the
306  /// @a val falls within this histogram's value range.
307  /// @return @c true if the sample value falls within this histogram's value range.
308  inline bool add(double val, uint64_t n = 1)
309  {
310  if (val<mMin || val>mMax) return false;
311  mBins[size_t(mDelta*(val-mMin))] += n;
312  mSize += n;
313  return true;
314  }
315 
316  /// @brief Add all the contributions from the other histogram, provided that
317  /// it has the same configuration as this histogram.
318  bool add(const Histogram& other)
319  {
320  if (!isApproxEqual(mMin, other.mMin) || !isApproxEqual(mMax, other.mMax) ||
321  mBins.size() != other.mBins.size()) return false;
322  for (size_t i=0, e=mBins.size(); i!=e; ++i) mBins[i] += other.mBins[i];
323  mSize += other.mSize;
324  return true;
325  }
326 
327  /// Return the number of bins in this histogram.
328  inline size_t numBins() const { return mBins.size(); }
329  /// Return the lower bound of this histogram's value range.
330  inline double min() const { return mMin; }
331  /// Return the upper bound of this histogram's value range.
332  inline double max() const { return mMax; }
333  /// Return the minimum value in the <i>n</i>th bin.
334  inline double min(int n) const { return mMin+n/mDelta; }
335  /// Return the maximum value in the <i>n</i>th bin.
336  inline double max(int n) const { return mMin+(n+1)/mDelta; }
337  /// Return the number of samples in the <i>n</i>th bin.
338  inline uint64_t count(int n) const { return mBins[n]; }
339  /// Return the population size, i.e., the total number of samples.
340  inline uint64_t size() const { return mSize; }
341 
342  /// Print the histogram to the specified output stream.
343  void print(const std::string& name = "", std::ostream& strm = std::cout) const
344  {
345  // Write to a temporary string stream so as not to affect the state
346  // (precision, field width, etc.) of the output stream.
347  std::ostringstream os;
348  os << std::setprecision(6) << std::setiosflags(std::ios::fixed) << std::endl;
349  os << "Histogram ";
350  if (!name.empty()) os << "for \"" << name << "\" ";
351  if (mSize > 0) {
352  os << "with " << mSize << " samples:\n";
353  os << "==============================================================\n";
354  os << "|| # | Min | Max | Frequency | % ||\n";
355  os << "==============================================================\n";
356  for (int i = 0, e = int(mBins.size()); i != e; ++i) {
357  os << "|| " << std::setw(4) << i << " | " << std::setw(14) << this->min(i) << " | "
358  << std::setw(14) << this->max(i) << " | " << std::setw(9) << mBins[i] << " | "
359  << std::setw(3) << (100*mBins[i]/mSize) << " ||\n";
360  }
361  os << "==============================================================\n";
362  } else {
363  os << ": no samples were added." << std::endl;
364  }
365  strm << os.str();
366  }
367 
368 private:
369  uint64_t mSize;
370  double mMin, mMax, mDelta;
371  std::vector<uint64_t> mBins;
372 };// end Histogram
373 
374 } // namespace math
375 } // namespace OPENVDB_VERSION_NAME
376 } // namespace openvdb
377 
378 #endif // OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
void join(const Extrema &other)
Definition: Stats.h:157
bool add(double val, uint64_t n=1)
Add n samples with constant value val, provided that the val falls within this histogram&#39;s value rang...
Definition: Stats.h:308
Definition: Exceptions.h:65
MinMax()
Empty constructor.
Definition: Stats.h:38
double mean() const
Return the arithmetic mean, i.e. average, value.
Definition: Stats.h:222
uint64_t count(int n) const
Return the number of samples in the nth bin.
Definition: Stats.h:338
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:74
void add(double val)
Add a single sample.
Definition: Stats.h:102
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
const ValueType & min() const
Return the minimum value.
Definition: Stats.h:56
Templated class to compute the minimum and maximum values.
Definition: Stats.h:30
Definition: Coord.h:589
void add(const Extrema &other)
Add the samples from the other Stats instance.
Definition: Stats.h:130
double stdDev() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance...
Definition: Stats.h:237
double std() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance...
Definition: Stats.h:236
size_t numBins() const
Return the number of bins in this histogram.
Definition: Stats.h:328
void add(double val)
Add a single sample.
Definition: Stats.h:189
This class computes the minimum and maximum values of a population of floating-point values...
Definition: Stats.h:88
double max() const
Return the upper bound of this histogram&#39;s value range.
Definition: Stats.h:332
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition: Stats.h:110
This class computes a histogram, with a fixed interval width, of a population of floating-point value...
Definition: Stats.h:275
Stats()
Definition: Stats.h:181
void print(const std::string &name="", std::ostream &strm=std::cout, int precision=3) const
Print MinMax to the specified output stream.
Definition: Stats.h:69
void print(const std::string &name="", std::ostream &strm=std::cout, int precision=3) const
Print extrema to the specified output stream.
Definition: Stats.h:136
double avg() const
Return the arithmetic mean, i.e. average, value.
Definition: Stats.h:221
void add(const MinMax &other, const Less &less=Less())
Add the samples from the other Stats instance.
Definition: Stats.h:62
double max(int n) const
Return the maximum value in the nth bin.
Definition: Stats.h:336
double min() const
Return the minimum value.
Definition: Stats.h:121
double min(int n) const
Return the minimum value in the nth bin.
Definition: Stats.h:334
double mAux
Definition: Stats.h:266
double max() const
Return the maximum value.
Definition: Stats.h:124
bool isApproxEqual(const Type &a, const Type &b, const Type &tolerance)
Return true if a is equal to b to within the given tolerance.
Definition: Math.h:406
double mAvg
Definition: Stats.h:266
Definition: Exceptions.h:13
double variance() const
Return the population variance.
Definition: Stats.h:230
void add(const ValueType &val, const Less &less=Less())
Add a single sample.
Definition: Stats.h:49
double min() const
Return the lower bound of this histogram&#39;s value range.
Definition: Stats.h:330
uint64_t size() const
Return the population size, i.e., the total number of samples.
Definition: Stats.h:340
void print(const std::string &name="", std::ostream &strm=std::cout, int precision=3) const
Print statistics to the specified output stream.
Definition: Stats.h:241
void add(const Stats &other)
Add the samples from the other Stats instance.
Definition: Stats.h:208
Histogram(const Stats &s, size_t numBins=10)
Construct with the given bin count and with minimum and maximum values taken from a Stats object...
Definition: Stats.h:293
Extrema()
Constructor.
Definition: Stats.h:94
const ValueType & max() const
Return the maximum value.
Definition: Stats.h:59
Histogram(double min, double max, size_t numBins=10)
Construct with given minimum and maximum values and the given bin count.
Definition: Stats.h:279
bool add(const Histogram &other)
Add all the contributions from the other histogram, provided that it has the same configuration as th...
Definition: Stats.h:318
This class computes statistics (minimum value, maximum value, mean, variance and standard deviation) ...
Definition: Stats.h:178
uint64_t size() const
Return the size of the population, i.e., the total number of samples.
Definition: Stats.h:118
double range() const
Return the range defined as the maximum value minus the minimum value.
Definition: Stats.h:127
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition: Stats.h:198
void print(const std::string &name="", std::ostream &strm=std::cout) const
Print the histogram to the specified output stream.
Definition: Stats.h:343
ValueType mMin
Definition: Stats.h:83
ValueType mMax
Definition: Stats.h:83
const std::enable_if<!VecTraits< T >::IsVec, T >::type & max(const T &a, const T &b)
Definition: Composite.h:110
double mMax
Definition: Stats.h:166
uint64_t mSize
Definition: Stats.h:165
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h.in:121
double mMin
Definition: Stats.h:166
MinMax(const ValueType &min, const ValueType &max)
Constructor.
Definition: Stats.h:45
const std::enable_if<!VecTraits< T >::IsVec, T >::type & min(const T &a, const T &b)
Definition: Composite.h:106
double var() const
Return the population variance.
Definition: Stats.h:229
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h.in:212