HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Stats.h
Go to the documentation of this file.
1 ///////////////////////////////////////////////////////////////////////////
2 //
3 // Copyright (c) 2012-2017 DreamWorks Animation LLC
4 //
5 // All rights reserved. This software is distributed under the
6 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
7 //
8 // Redistributions of source code must retain the above copyright
9 // and license notice and the following restrictions and disclaimer.
10 //
11 // * Neither the name of DreamWorks Animation nor the names of
12 // its contributors may be used to endorse or promote products derived
13 // from this software without specific prior written permission.
14 //
15 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
19 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY INDIRECT, INCIDENTAL,
20 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
21 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 // IN NO EVENT SHALL THE COPYRIGHT HOLDERS' AND CONTRIBUTORS' AGGREGATE
27 // LIABILITY FOR ALL CLAIMS REGARDLESS OF THEIR BASIS EXCEED US$250.00.
28 //
29 ///////////////////////////////////////////////////////////////////////////
30 //
31 /// @file Stats.h
32 ///
33 /// @author Ken Museth
34 ///
35 /// @brief Classes to compute statistics and histograms
36 
37 #ifndef OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
38 #define OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
39 
40 #include <iosfwd> // for ostringstream
41 #include <openvdb/version.h>
42 #include <iostream>
43 #include <iomanip>
44 #include <sstream>
45 #include <vector>
46 #include <functional>// for std::less
47 #include "Math.h"
48 
49 namespace openvdb {
51 namespace OPENVDB_VERSION_NAME {
52 namespace math {
53 
54 /// @brief Templated class to compute the minimum and maximum values.
55 template <typename ValueType, typename Less = std::less<ValueType> >
56 class MinMax
57 {
58 public:
59 
60  /// @brief Constructor
61  MinMax(const ValueType &min, const ValueType &max) : mMin(min), mMax(max)
62  {
63  }
64 
65  /// Add a single sample.
66  inline void add(const ValueType &val, const Less &less = Less())
67  {
68  if (less(val, mMin)) mMin = val;
69  if (less(mMax, val)) mMax = val;
70  }
71 
72  /// Return the minimum value.
73  inline const ValueType& min() const { return mMin; }
74 
75  /// Return the maximum value.
76  inline const ValueType& max() const { return mMax; }
77 
78  /// Add the samples from the other Stats instance.
79  inline void add(const MinMax& other, const Less &less = Less())
80  {
81  if (less(other.mMin, mMin)) mMin = other.mMin;
82  if (less(mMax, other.mMax)) mMax = other.mMax;
83  }
84 
85  /// @brief Print MinMax to the specified output stream.
86  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
87  {
88  // Write to a temporary string stream so as not to affect the state
89  // (precision, field width, etc.) of the output stream.
90  std::ostringstream os;
91  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
92  os << "MinMax ";
93  if (!name.empty()) os << "for \"" << name << "\" ";
94  os << " Min=" << mMin << ", Max=" << mMax << std::endl;
95  strm << os.str();
96  }
97 
98 protected:
99 
100  ValueType mMin, mMax;
101 };//end MinMax
102 
103 /// @brief This class computes the minimum and maximum values of a population
104 /// of floating-point values.
105 class Extrema
106 {
107 public:
108 
109  /// @brief Constructor
110  /// @warning The min/max values are initiated to extreme values
112  : mSize(0)
113  , mMin(std::numeric_limits<double>::max())
114  , mMax(-mMin)
115  {
116  }
117 
118  /// Add a single sample.
119  void add(double val)
120  {
121  ++mSize;
122  mMin = std::min<double>(val, mMin);
123  mMax = std::max<double>(val, mMax);
124  }
125 
126  /// Add @a n samples with constant value @a val.
127  void add(double val, uint64_t n)
128  {
129  mSize += n;
130  mMin = std::min<double>(val, mMin);
131  mMax = std::max<double>(val, mMax);
132  }
133 
134  /// Return the size of the population, i.e., the total number of samples.
135  inline uint64_t size() const { return mSize; }
136 
137  /// Return the minimum value.
138  inline double min() const { return mMin; }
139 
140  /// Return the maximum value.
141  inline double max() const { return mMax; }
142 
143  /// Return the range defined as the maximum value minus the minimum value.
144  inline double range() const { return mMax - mMin; }
145 
146  /// Add the samples from the other Stats instance.
147  void add(const Extrema& other)
148  {
149  if (other.mSize > 0) this->join(other);
150  }
151 
152  /// @brief Print extrema to the specified output stream.
153  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
154  {
155  // Write to a temporary string stream so as not to affect the state
156  // (precision, field width, etc.) of the output stream.
157  std::ostringstream os;
158  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
159  os << "Extrema ";
160  if (!name.empty()) os << "for \"" << name << "\" ";
161  if (mSize>0) {
162  os << "with " << mSize << " samples:\n"
163  << " Min=" << mMin
164  << ", Max=" << mMax
165  << ", Range="<< this->range() << std::endl;
166  } else {
167  os << ": no samples were added." << std::endl;
168  }
169  strm << os.str();
170  }
171 
172 protected:
173 
174  inline void join(const Extrema& other)
175  {
176  assert(other.mSize > 0);
177  mSize += other.mSize;
178  mMin = std::min<double>(mMin, other.mMin);
179  mMax = std::max<double>(mMax, other.mMax);
180  }
181 
182  uint64_t mSize;
183  double mMin, mMax;
184 };//end Extrema
185 
186 
187 /// @brief This class computes statistics (minimum value, maximum
188 /// value, mean, variance and standard deviation) of a population
189 /// of floating-point values.
190 ///
191 /// @details variance = Mean[ (X-Mean[X])^2 ] = Mean[X^2] - Mean[X]^2,
192 /// standard deviation = sqrt(variance)
193 ///
194 /// @note This class employs incremental computation and double precision.
195 class Stats : public Extrema
196 {
197 public:
199  : Extrema()
200  , mAvg(0.0)
201  , mAux(0.0)
202  {
203  }
204 
205  /// Add a single sample.
206  void add(double val)
207  {
208  Extrema::add(val);
209  const double delta = val - mAvg;
210  mAvg += delta/double(mSize);
211  mAux += delta*(val - mAvg);
212  }
213 
214  /// Add @a n samples with constant value @a val.
215  void add(double val, uint64_t n)
216  {
217  const double denom = 1.0/double(mSize + n);
218  const double delta = val - mAvg;
219  mAvg += denom * delta * double(n);
220  mAux += denom * delta * delta * double(mSize) * double(n);
221  Extrema::add(val, n);
222  }
223 
224  /// Add the samples from the other Stats instance.
225  void add(const Stats& other)
226  {
227  if (other.mSize > 0) {
228  const double denom = 1.0/double(mSize + other.mSize);
229  const double delta = other.mAvg - mAvg;
230  mAvg += denom * delta * double(other.mSize);
231  mAux += other.mAux + denom * delta * delta * double(mSize) * double(other.mSize);
232  Extrema::join(other);
233  }
234  }
235 
236  //@{
237  /// Return the arithmetic mean, i.e. average, value.
238  inline double avg() const { return mAvg; }
239  inline double mean() const { return mAvg; }
240  //@}
241 
242  //@{
243  /// @brief Return the population variance.
244  /// @note The unbiased sample variance = population variance *
245  //num/(num-1)
246  inline double var() const { return mSize<2 ? 0.0 : mAux/double(mSize); }
247  inline double variance() const { return this->var(); }
248  //@}
249 
250  //@{
251  /// @brief Return the standard deviation (=Sqrt(variance)) as
252  /// defined from the (biased) population variance.
253  inline double std() const { return sqrt(this->var()); }
254  inline double stdDev() const { return this->std(); }
255  //@}
256 
257  /// @brief Print statistics to the specified output stream.
258  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
259  {
260  // Write to a temporary string stream so as not to affect the state
261  // (precision, field width, etc.) of the output stream.
262  std::ostringstream os;
263  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
264  os << "Statistics ";
265  if (!name.empty()) os << "for \"" << name << "\" ";
266  if (mSize>0) {
267  os << "with " << mSize << " samples:\n"
268  << " Min=" << mMin
269  << ", Max=" << mMax
270  << ", Ave=" << mAvg
271  << ", Std=" << this->stdDev()
272  << ", Var=" << this->variance() << std::endl;
273  } else {
274  os << ": no samples were added." << std::endl;
275  }
276  strm << os.str();
277  }
278 
279 protected:
280  using Extrema::mSize;
281  using Extrema::mMin;
282  using Extrema::mMax;
283  double mAvg, mAux;
284 }; // end Stats
285 
286 
287 ////////////////////////////////////////
288 
289 
290 /// @brief This class computes a histogram, with a fixed interval width,
291 /// of a population of floating-point values.
293 {
294 public:
295  /// Construct with given minimum and maximum values and the given bin count.
296  Histogram(double min, double max, size_t numBins = 10)
297  : mSize(0), mMin(min), mMax(max + 1e-10),
298  mDelta(double(numBins)/(max-min)), mBins(numBins)
299  {
300  if ( mMax <= mMin ) {
301  OPENVDB_THROW(ValueError, "Histogram: expected min < max");
302  } else if ( numBins == 0 ) {
303  OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
304  }
305  for (size_t i=0; i<numBins; ++i) mBins[i]=0;
306  }
307 
308  /// @brief Construct with the given bin count and with minimum and maximum values
309  /// taken from a Stats object.
310  Histogram(const Stats& s, size_t numBins = 10):
311  mSize(0), mMin(s.min()), mMax(s.max()+1e-10),
312  mDelta(double(numBins)/(mMax-mMin)), mBins(numBins)
313  {
314  if ( mMax <= mMin ) {
315  OPENVDB_THROW(ValueError, "Histogram: expected min < max");
316  } else if ( numBins == 0 ) {
317  OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
318  }
319  for (size_t i=0; i<numBins; ++i) mBins[i]=0;
320  }
321 
322  /// @brief Add @a n samples with constant value @a val, provided that the
323  /// @a val falls within this histogram's value range.
324  /// @return @c true if the sample value falls within this histogram's value range.
325  inline bool add(double val, uint64_t n = 1)
326  {
327  if (val<mMin || val>mMax) return false;
328  mBins[size_t(mDelta*(val-mMin))] += n;
329  mSize += n;
330  return true;
331  }
332 
333  /// @brief Add all the contributions from the other histogram, provided that
334  /// it has the same configuration as this histogram.
335  bool add(const Histogram& other)
336  {
337  if (!isApproxEqual(mMin, other.mMin) || !isApproxEqual(mMax, other.mMax) ||
338  mBins.size() != other.mBins.size()) return false;
339  for (size_t i=0, e=mBins.size(); i!=e; ++i) mBins[i] += other.mBins[i];
340  mSize += other.mSize;
341  return true;
342  }
343 
344  /// Return the number of bins in this histogram.
345  inline size_t numBins() const { return mBins.size(); }
346  /// Return the lower bound of this histogram's value range.
347  inline double min() const { return mMin; }
348  /// Return the upper bound of this histogram's value range.
349  inline double max() const { return mMax; }
350  /// Return the minimum value in the <i>n</i>th bin.
351  inline double min(int n) const { return mMin+n/mDelta; }
352  /// Return the maximum value in the <i>n</i>th bin.
353  inline double max(int n) const { return mMin+(n+1)/mDelta; }
354  /// Return the number of samples in the <i>n</i>th bin.
355  inline uint64_t count(int n) const { return mBins[n]; }
356  /// Return the population size, i.e., the total number of samples.
357  inline uint64_t size() const { return mSize; }
358 
359  /// Print the histogram to the specified output stream.
360  void print(const std::string& name = "", std::ostream& strm = std::cout) const
361  {
362  // Write to a temporary string stream so as not to affect the state
363  // (precision, field width, etc.) of the output stream.
364  std::ostringstream os;
365  os << std::setprecision(6) << std::setiosflags(std::ios::fixed) << std::endl;
366  os << "Histogram ";
367  if (!name.empty()) os << "for \"" << name << "\" ";
368  if (mSize > 0) {
369  os << "with " << mSize << " samples:\n";
370  os << "==============================================================\n";
371  os << "|| # | Min | Max | Frequency | % ||\n";
372  os << "==============================================================\n";
373  for (int i = 0, e = int(mBins.size()); i != e; ++i) {
374  os << "|| " << std::setw(4) << i << " | " << std::setw(14) << this->min(i) << " | "
375  << std::setw(14) << this->max(i) << " | " << std::setw(9) << mBins[i] << " | "
376  << std::setw(3) << (100*mBins[i]/mSize) << " ||\n";
377  }
378  os << "==============================================================\n";
379  } else {
380  os << ": no samples were added." << std::endl;
381  }
382  strm << os.str();
383  }
384 
385 private:
386  uint64_t mSize;
387  double mMin, mMax, mDelta;
388  std::vector<uint64_t> mBins;
389 };
390 
391 } // namespace math
392 } // namespace OPENVDB_VERSION_NAME
393 } // namespace openvdb
394 
395 #endif // OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
396 
397 // Copyright (c) 2012-2017 DreamWorks Animation LLC
398 // All rights reserved. This software is distributed under the
399 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
GLsizei const GLchar *const * string
Definition: glcorearb.h:813
double stdDev() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance...
Definition: Stats.h:254
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:335
void add(const Extrema &other)
Add the samples from the other Stats instance.
Definition: Stats.h:147
void add(const ValueType &val, const Less &less=Less())
Add a single sample.
Definition: Stats.h:66
void print(const std::string &name="", std::ostream &strm=std::cout) const
Print the histogram to the specified output stream.
Definition: Stats.h:360
png_uint_32 i
Definition: png.h:2877
uint64_t size() const
Return the population size, i.e., the total number of samples.
Definition: Stats.h:357
void add(const MinMax &other, const Less &less=Less())
Add the samples from the other Stats instance.
Definition: Stats.h:79
uint64_t count(int n) const
Return the number of samples in the nth bin.
Definition: Stats.h:355
GLdouble n
Definition: glcorearb.h:2007
double mean() const
Return the arithmetic mean, i.e. average, value.
Definition: Stats.h:239
double min(int n) const
Return the minimum value in the nth bin.
Definition: Stats.h:351
#define OPENVDB_VERSION_NAME
Definition: version.h:43
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
size_t numBins() const
Return the number of bins in this histogram.
Definition: Stats.h:345
double variance() const
Return the population variance.
Definition: Stats.h:247
double max(int n) const
Return the maximum value in the nth bin.
Definition: Stats.h:353
void join(const Extrema &other)
Definition: Stats.h:174
const ValueType & max() const
Return the maximum value.
Definition: Stats.h:76
double range() const
Return the range defined as the maximum value minus the minimum value.
Definition: Stats.h:144
This class computes statistics (minimum value, maximum value, mean, variance and standard deviation) ...
Definition: Stats.h:195
void add(double val)
Add a single sample.
Definition: Stats.h:206
double avg() const
Return the arithmetic mean, i.e. average, value.
Definition: Stats.h:238
uint64_t size() const
Return the size of the population, i.e., the total number of samples.
Definition: Stats.h:135
GLuint const GLchar * name
Definition: glcorearb.h:785
Templated class to compute the minimum and maximum values.
Definition: Stats.h:56
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:258
MinMax(const ValueType &min, const ValueType &max)
Constructor.
Definition: Stats.h:61
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition: Stats.h:215
double min() const
Return the minimum value.
Definition: Stats.h:138
bool isApproxEqual(const Type &a, const Type &b)
Return true if a is equal to b to within the default floating-point comparison tolerance.
Definition: Math.h:370
double min() const
Return the lower bound of this histogram's value range.
Definition: Stats.h:347
GLenum GLint GLint * precision
Definition: glcorearb.h:1924
This class computes a histogram, with a fixed interval width, of a population of floating-point value...
Definition: Stats.h:292
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition: Stats.h:127
void add(const Stats &other)
Add the samples from the other Stats instance.
Definition: Stats.h:225
double var() const
Return the population variance.
Definition: Stats.h:246
const ValueType & min() const
Return the minimum value.
Definition: Stats.h:73
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:86
GLuint GLfloat * val
Definition: glcorearb.h:1607
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:153
double max() const
Return the upper bound of this histogram's value range.
Definition: Stats.h:349
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:310
Histogram(double min, double max, size_t numBins=10)
Construct with given minimum and maximum values and the given bin count.
Definition: Stats.h:296
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:71
bool add(double val, uint64_t n=1)
Add n samples with constant value val, provided that the val falls within this histogram's value rang...
Definition: Stats.h:325
double max() const
Return the maximum value.
Definition: Stats.h:141
double std() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance...
Definition: Stats.h:253
void add(double val)
Add a single sample.
Definition: Stats.h:119
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:101
This class computes the minimum and maximum values of a population of floating-point values...
Definition: Stats.h:105