OpenVDB: openvdb/math/Stats.h Source File

OpenVDB 12.1.1

Loading...
Searching...
No Matches
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
24namespace openvdb {
25 OPENVDB_USE_VERSION_NAMESPACE
26namespace OPENVDB_VERSION_NAME {
27namespace math {
28
29/// @brief Templated class to compute the minimum and maximum values.
30template <typename ValueType, typename Less = std::less<ValueType> >
31 class MinMax
32{
33 using Limits = std::numeric_limits<ValueType>;
34public:
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
82protected:
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{
91public:
92
93 /// @brief Constructor
94 /// @warning The min/max values are initiated to extreme values
95 Extrema()
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
156protected:
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{
181public:
182 Stats()
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
263protected:
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.
276 class Histogram
277{
278public:
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
369private:
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
Assert.h
OPENVDB_ASSERT
#define OPENVDB_ASSERT(X)
Definition Assert.h:41
Math.h
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
openvdb::v12_1::ValueError
Definition Exceptions.h:65
openvdb::v12_1::math::Extrema::add
void add(double val)
Add a single sample.
Definition Stats.h:103
openvdb::v12_1::math::Extrema::add
void add(const Extrema &other)
Add the samples from the other Stats instance.
Definition Stats.h:131
openvdb::v12_1::math::Extrema::Extrema
Extrema()
Constructor.
Definition Stats.h:95
openvdb::v12_1::math::Extrema::mMax
double mMax
Definition Stats.h:167
openvdb::v12_1::math::Extrema::mSize
uint64_t mSize
Definition Stats.h:166
openvdb::v12_1::math::Extrema::range
double range() const
Return the range defined as the maximum value minus the minimum value.
Definition Stats.h:128
openvdb::v12_1::math::Extrema::min
double min() const
Return the minimum value.
Definition Stats.h:122
openvdb::v12_1::math::Extrema::size
uint64_t size() const
Return the size of the population, i.e., the total number of samples.
Definition Stats.h:119
openvdb::v12_1::math::Extrema::add
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition Stats.h:111
openvdb::v12_1::math::Extrema::join
void join(const Extrema &other)
Definition Stats.h:158
openvdb::v12_1::math::Extrema::mMin
double mMin
Definition Stats.h:167
openvdb::v12_1::math::Extrema::print
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
openvdb::v12_1::math::Extrema::max
double max() const
Return the maximum value.
Definition Stats.h:125
openvdb::v12_1::math::Histogram::print
void print(const std::string &name="", std::ostream &strm=std::cout) const
Print the histogram to the specified output stream.
Definition Stats.h:344
openvdb::v12_1::math::Histogram::count
uint64_t count(int n) const
Return the number of samples in the nth bin.
Definition Stats.h:339
openvdb::v12_1::math::Histogram::add
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:309
openvdb::v12_1::math::Histogram::min
double min(int n) const
Return the minimum value in the nth bin.
Definition Stats.h:335
openvdb::v12_1::math::Histogram::min
double min() const
Return the lower bound of this histogram's value range.
Definition Stats.h:331
openvdb::v12_1::math::Histogram::size
uint64_t size() const
Return the population size, i.e., the total number of samples.
Definition Stats.h:341
openvdb::v12_1::math::Histogram::Histogram
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
openvdb::v12_1::math::Histogram::max
double max(int n) const
Return the maximum value in the nth bin.
Definition Stats.h:337
openvdb::v12_1::math::Histogram::numBins
size_t numBins() const
Return the number of bins in this histogram.
Definition Stats.h:329
openvdb::v12_1::math::Histogram::add
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
openvdb::v12_1::math::Histogram::max
double max() const
Return the upper bound of this histogram's value range.
Definition Stats.h:333
openvdb::v12_1::math::Histogram::Histogram
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
openvdb::v12_1::math::MinMax::mMin
ValueType mMin
Definition Stats.h:84
openvdb::v12_1::math::MinMax::mMax
ValueType mMax
Definition Stats.h:84
openvdb::v12_1::math::MinMax::max
const ValueType & max() const
Return the maximum value.
Definition Stats.h:60
openvdb::v12_1::math::MinMax::add
void add(const ValueType &val, const Less &less=Less())
Add a single sample.
Definition Stats.h:50
openvdb::v12_1::math::MinMax::MinMax
MinMax(const ValueType &min, const ValueType &max)
Constructor.
Definition Stats.h:46
openvdb::v12_1::math::MinMax::print
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
openvdb::v12_1::math::MinMax::MinMax
MinMax()
Empty constructor.
Definition Stats.h:39
openvdb::v12_1::math::MinMax::min
const ValueType & min() const
Return the minimum value.
Definition Stats.h:57
openvdb::v12_1::math::MinMax::add
void add(const MinMax &other, const Less &less=Less())
Add the samples from the other Stats instance.
Definition Stats.h:63
openvdb::v12_1::math::Stats
This class computes statistics (minimum value, maximum value, mean, variance and standard deviation) ...
Definition Stats.h:180
openvdb::v12_1::math::Stats::var
double var() const
Return the population variance.
Definition Stats.h:230
openvdb::v12_1::math::Stats::add
void add(double val)
Add a single sample.
Definition Stats.h:190
openvdb::v12_1::math::Stats::mAvg
double mAvg
Definition Stats.h:267
openvdb::v12_1::math::Stats::mMax
double mMax
Definition Stats.h:167
openvdb::v12_1::math::Stats::add
void add(const Stats &other)
Add the samples from the other Stats instance.
Definition Stats.h:209
openvdb::v12_1::math::Stats::mSize
uint64_t mSize
Definition Stats.h:166
openvdb::v12_1::math::Stats::mean
double mean() const
Definition Stats.h:223
openvdb::v12_1::math::Stats::variance
double variance() const
Definition Stats.h:231
openvdb::v12_1::math::Stats::add
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition Stats.h:199
openvdb::v12_1::math::Stats::stdDev
double stdDev() const
Definition Stats.h:238
openvdb::v12_1::math::Stats::mAux
double mAux
Definition Stats.h:267
openvdb::v12_1::math::Stats::mMin
double mMin
Definition Stats.h:167
openvdb::v12_1::math::Stats::std
double std() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance.
Definition Stats.h:237
openvdb::v12_1::math::Stats::print
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
openvdb::v12_1::math::Stats::avg
double avg() const
Return the arithmetic mean, i.e. average, value.
Definition Stats.h:222
openvdb::v12_1::math::Stats::Stats
Stats()
Definition Stats.h:182
openvdb::v12_1::math::isApproxEqual
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
openvdb
Definition Exceptions.h:13
std
Definition Coord.h:590
Exceptions.h
OPENVDB_THROW
#define OPENVDB_THROW(exception, message)
Definition Exceptions.h:74
OPENVDB_VERSION_NAME
#define OPENVDB_VERSION_NAME
The version namespace name for this library version.
Definition version.h.in:121
OPENVDB_USE_VERSION_NAMESPACE
#define OPENVDB_USE_VERSION_NAMESPACE
Definition version.h.in:218