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