OpenVDB  5.0.0
Stats.h
Go to the documentation of this file.
1 //
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 //
30 //
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 
55 template <typename ValueType, typename Less = std::less<ValueType> >
56 class MinMax
57 {
58  using Limits = std::numeric_limits<ValueType>;
59 public:
60 
64  MinMax() : mMin(Limits::max()), mMax(Limits::lowest())
65  {
66  static_assert(std::numeric_limits<ValueType>::is_specialized,
67  "openvdb::math::MinMax default constructor requires a std::numeric_limits specialization");
68  }
69 
71  MinMax(const ValueType &min, const ValueType &max) : mMin(min), mMax(max)
72  {
73  }
74 
76  MinMax(const MinMax &other) = default;
77 
79  inline void add(const ValueType &val, const Less &less = Less())
80  {
81  if (less(val, mMin)) mMin = val;
82  if (less(mMax, val)) mMax = val;
83  }
84 
86  inline const ValueType& min() const { return mMin; }
87 
89  inline const ValueType& max() const { return mMax; }
90 
92  inline void add(const MinMax& other, const Less &less = Less())
93  {
94  if (less(other.mMin, mMin)) mMin = other.mMin;
95  if (less(mMax, other.mMax)) mMax = other.mMax;
96  }
97 
99  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
100  {
101  // Write to a temporary string stream so as not to affect the state
102  // (precision, field width, etc.) of the output stream.
103  std::ostringstream os;
104  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
105  os << "MinMax ";
106  if (!name.empty()) os << "for \"" << name << "\" ";
107  os << " Min=" << mMin << ", Max=" << mMax << std::endl;
108  strm << os.str();
109  }
110 
111 protected:
112 
113  ValueType mMin, mMax;
114 };//end MinMax
115 
118 class Extrema
119 {
120 public:
121 
125  : mSize(0)
126  , mMin(std::numeric_limits<double>::max())
127  , mMax(-mMin)
128  {
129  }
130 
132  void add(double val)
133  {
134  ++mSize;
135  mMin = std::min<double>(val, mMin);
136  mMax = std::max<double>(val, mMax);
137  }
138 
140  void add(double val, uint64_t n)
141  {
142  mSize += n;
143  mMin = std::min<double>(val, mMin);
144  mMax = std::max<double>(val, mMax);
145  }
146 
148  inline uint64_t size() const { return mSize; }
149 
151  inline double min() const { return mMin; }
152 
154  inline double max() const { return mMax; }
155 
157  inline double range() const { return mMax - mMin; }
158 
160  void add(const Extrema& other)
161  {
162  if (other.mSize > 0) this->join(other);
163  }
164 
166  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
167  {
168  // Write to a temporary string stream so as not to affect the state
169  // (precision, field width, etc.) of the output stream.
170  std::ostringstream os;
171  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
172  os << "Extrema ";
173  if (!name.empty()) os << "for \"" << name << "\" ";
174  if (mSize>0) {
175  os << "with " << mSize << " samples:\n"
176  << " Min=" << mMin
177  << ", Max=" << mMax
178  << ", Range="<< this->range() << std::endl;
179  } else {
180  os << ": no samples were added." << std::endl;
181  }
182  strm << os.str();
183  }
184 
185 protected:
186 
187  inline void join(const Extrema& other)
188  {
189  assert(other.mSize > 0);
190  mSize += other.mSize;
191  mMin = std::min<double>(mMin, other.mMin);
192  mMax = std::max<double>(mMax, other.mMax);
193  }
194 
195  uint64_t mSize;
196  double mMin, mMax;
197 };//end Extrema
198 
199 
208 class Stats : public Extrema
209 {
210 public:
212  : Extrema()
213  , mAvg(0.0)
214  , mAux(0.0)
215  {
216  }
217 
219  void add(double val)
220  {
221  Extrema::add(val);
222  const double delta = val - mAvg;
223  mAvg += delta/double(mSize);
224  mAux += delta*(val - mAvg);
225  }
226 
228  void add(double val, uint64_t n)
229  {
230  const double denom = 1.0/double(mSize + n);
231  const double delta = val - mAvg;
232  mAvg += denom * delta * double(n);
233  mAux += denom * delta * delta * double(mSize) * double(n);
234  Extrema::add(val, n);
235  }
236 
238  void add(const Stats& other)
239  {
240  if (other.mSize > 0) {
241  const double denom = 1.0/double(mSize + other.mSize);
242  const double delta = other.mAvg - mAvg;
243  mAvg += denom * delta * double(other.mSize);
244  mAux += other.mAux + denom * delta * delta * double(mSize) * double(other.mSize);
245  Extrema::join(other);
246  }
247  }
248 
250  inline double avg() const { return mAvg; }
252  inline double mean() const { return mAvg; }
254 
256  //num/(num-1)
259  inline double var() const { return mSize<2 ? 0.0 : mAux/double(mSize); }
260  inline double variance() const { return this->var(); }
262 
264  inline double std() const { return sqrt(this->var()); }
267  inline double stdDev() const { return this->std(); }
269 
271  void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
272  {
273  // Write to a temporary string stream so as not to affect the state
274  // (precision, field width, etc.) of the output stream.
275  std::ostringstream os;
276  os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
277  os << "Statistics ";
278  if (!name.empty()) os << "for \"" << name << "\" ";
279  if (mSize>0) {
280  os << "with " << mSize << " samples:\n"
281  << " Min=" << mMin
282  << ", Max=" << mMax
283  << ", Ave=" << mAvg
284  << ", Std=" << this->stdDev()
285  << ", Var=" << this->variance() << std::endl;
286  } else {
287  os << ": no samples were added." << std::endl;
288  }
289  strm << os.str();
290  }
291 
292 protected:
293  using Extrema::mSize;
294  using Extrema::mMin;
295  using Extrema::mMax;
296  double mAvg, mAux;
297 }; // end Stats
298 
299 
301 
302 
306 {
307 public:
309  Histogram(double min, double max, size_t numBins = 10)
310  : mSize(0), mMin(min), mMax(max + 1e-10),
311  mDelta(double(numBins)/(max-min)), mBins(numBins)
312  {
313  if ( mMax <= mMin ) {
314  OPENVDB_THROW(ValueError, "Histogram: expected min < max");
315  } else if ( numBins == 0 ) {
316  OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
317  }
318  for (size_t i=0; i<numBins; ++i) mBins[i]=0;
319  }
320 
323  Histogram(const Stats& s, size_t numBins = 10):
324  mSize(0), mMin(s.min()), mMax(s.max()+1e-10),
325  mDelta(double(numBins)/(mMax-mMin)), mBins(numBins)
326  {
327  if ( mMax <= mMin ) {
328  OPENVDB_THROW(ValueError, "Histogram: expected min < max");
329  } else if ( numBins == 0 ) {
330  OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
331  }
332  for (size_t i=0; i<numBins; ++i) mBins[i]=0;
333  }
334 
338  inline bool add(double val, uint64_t n = 1)
339  {
340  if (val<mMin || val>mMax) return false;
341  mBins[size_t(mDelta*(val-mMin))] += n;
342  mSize += n;
343  return true;
344  }
345 
348  bool add(const Histogram& other)
349  {
350  if (!isApproxEqual(mMin, other.mMin) || !isApproxEqual(mMax, other.mMax) ||
351  mBins.size() != other.mBins.size()) return false;
352  for (size_t i=0, e=mBins.size(); i!=e; ++i) mBins[i] += other.mBins[i];
353  mSize += other.mSize;
354  return true;
355  }
356 
358  inline size_t numBins() const { return mBins.size(); }
360  inline double min() const { return mMin; }
362  inline double max() const { return mMax; }
364  inline double min(int n) const { return mMin+n/mDelta; }
366  inline double max(int n) const { return mMin+(n+1)/mDelta; }
368  inline uint64_t count(int n) const { return mBins[n]; }
370  inline uint64_t size() const { return mSize; }
371 
373  void print(const std::string& name = "", std::ostream& strm = std::cout) const
374  {
375  // Write to a temporary string stream so as not to affect the state
376  // (precision, field width, etc.) of the output stream.
377  std::ostringstream os;
378  os << std::setprecision(6) << std::setiosflags(std::ios::fixed) << std::endl;
379  os << "Histogram ";
380  if (!name.empty()) os << "for \"" << name << "\" ";
381  if (mSize > 0) {
382  os << "with " << mSize << " samples:\n";
383  os << "==============================================================\n";
384  os << "|| # | Min | Max | Frequency | % ||\n";
385  os << "==============================================================\n";
386  for (int i = 0, e = int(mBins.size()); i != e; ++i) {
387  os << "|| " << std::setw(4) << i << " | " << std::setw(14) << this->min(i) << " | "
388  << std::setw(14) << this->max(i) << " | " << std::setw(9) << mBins[i] << " | "
389  << std::setw(3) << (100*mBins[i]/mSize) << " ||\n";
390  }
391  os << "==============================================================\n";
392  } else {
393  os << ": no samples were added." << std::endl;
394  }
395  strm << os.str();
396  }
397 
398 private:
399  uint64_t mSize;
400  double mMin, mMax, mDelta;
401  std::vector<uint64_t> mBins;
402 };// end Histogram
403 
404 } // namespace math
405 } // namespace OPENVDB_VERSION_NAME
406 } // namespace openvdb
407 
408 #endif // OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
409 
410 // Copyright (c) 2012-2017 DreamWorks Animation LLC
411 // All rights reserved. This software is distributed under the
412 // Mozilla Public License 2.0 ( http://www.mozilla.org/MPL/2.0/ )
Templated class to compute the minimum and maximum values.
Definition: Stats.h:56
double max() const
Return the maximum value.
Definition: Stats.h:154
ValueType mMax
Definition: Stats.h:113
double stdDev() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance...
Definition: Stats.h:267
const std::enable_if<!VecTraits< T >::IsVec, T >::type & max(const T &a, const T &b)
Definition: Composite.h:133
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
uint64_t mSize
Definition: Stats.h:195
This class computes the minimum and maximum values of a population of floating-point values...
Definition: Stats.h:118
#define OPENVDB_THROW(exception, message)
Definition: Exceptions.h:108
double mAvg
Definition: Stats.h:296
uint64_t mSize
Definition: Stats.h:195
void add(const Stats &other)
Add the samples from the other Stats instance.
Definition: Stats.h:238
void add(double val)
Add a single sample.
Definition: Stats.h:219
const std::enable_if<!VecTraits< T >::IsVec, T >::type & min(const T &a, const T &b)
Definition: Composite.h:129
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:354
Extrema()
Constructor.
Definition: Stats.h:124
uint64_t count(int n) const
Return the number of samples in the nth bin.
Definition: Stats.h:368
const ValueType & max() const
Return the maximum value.
Definition: Stats.h:89
double mAux
Definition: Stats.h:296
void add(const MinMax &other, const Less &less=Less())
Add the samples from the other Stats instance.
Definition: Stats.h:92
double var() const
Return the population variance.
Definition: Stats.h:259
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition: version.h:136
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition: Stats.h:140
Stats()
Definition: Stats.h:211
uint64_t size() const
Return the size of the population, i.e., the total number of samples.
Definition: Stats.h:148
double mMax
Definition: Stats.h:196
Definition: Exceptions.h:91
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:271
double mMin
Definition: Stats.h:196
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:99
double variance() const
Return the population variance.
Definition: Stats.h:260
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:323
double min(int n) const
Return the minimum value in the nth bin.
Definition: Stats.h:364
const ValueType & min() const
Return the minimum value.
Definition: Stats.h:86
double range() const
Return the range defined as the maximum value minus the minimum value.
Definition: Stats.h:157
This class computes statistics (minimum value, maximum value, mean, variance and standard deviation) ...
Definition: Stats.h:208
Definition: Exceptions.h:39
void add(double val)
Add a single sample.
Definition: Stats.h:132
void print(const std::string &name="", std::ostream &strm=std::cout) const
Print the histogram to the specified output stream.
Definition: Stats.h:373
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:348
double max() const
Return the upper bound of this histogram&#39;s value range.
Definition: Stats.h:362
Library and file format version numbers.
This class computes a histogram, with a fixed interval width, of a population of floating-point value...
Definition: Stats.h:305
MinMax(const ValueType &min, const ValueType &max)
Constructor.
Definition: Stats.h:71
void join(const Extrema &other)
Definition: Stats.h:187
double mean() const
Return the arithmetic mean, i.e. average, value.
Definition: Stats.h:252
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition: Stats.h:228
void add(const ValueType &val, const Less &less=Less())
Add a single sample.
Definition: Stats.h:79
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:338
size_t numBins() const
Return the number of bins in this histogram.
Definition: Stats.h:358
double min() const
Return the lower bound of this histogram&#39;s value range.
Definition: Stats.h:360
double min() const
Return the minimum value.
Definition: Stats.h:151
uint64_t size() const
Return the population size, i.e., the total number of samples.
Definition: Stats.h:370
#define OPENVDB_USE_VERSION_NAMESPACE
Definition: version.h:188
ValueType mMin
Definition: Stats.h:113
MinMax()
Empty constructor.
Definition: Stats.h:64
double max(int n) const
Return the maximum value in the nth bin.
Definition: Stats.h:366
Histogram(double min, double max, size_t numBins=10)
Construct with given minimum and maximum values and the given bin count.
Definition: Stats.h:309
void add(const Extrema &other)
Add the samples from the other Stats instance.
Definition: Stats.h:160
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:166