OpenVDB: openvdb/math/Stats.h Source File

OpenVDB 11.0.0

Loading...
Searching...
No Matches
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
23namespace openvdb {
24 OPENVDB_USE_VERSION_NAMESPACE
25namespace OPENVDB_VERSION_NAME {
26namespace math {
27
28/// @brief Templated class to compute the minimum and maximum values.
29template <typename ValueType, typename Less = std::less<ValueType> >
30 class MinMax
31{
32 using Limits = std::numeric_limits<ValueType>;
33public:
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
81protected:
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{
90public:
91
92 /// @brief Constructor
93 /// @warning The min/max values are initiated to extreme values
94 Extrema()
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
155protected:
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{
180public:
181 Stats()
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
262protected:
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.
275 class Histogram
276{
277public:
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
368private:
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
Math.h
General-purpose arithmetic and comparison routines, most of which accept arbitrary value types (or at...
openvdb::v11_0::ValueError
Definition Exceptions.h:65
openvdb::v11_0::math::Extrema
This class computes the minimum and maximum values of a population of floating-point values.
Definition Stats.h:89
openvdb::v11_0::math::Extrema::add
void add(double val)
Add a single sample.
Definition Stats.h:102
openvdb::v11_0::math::Extrema::add
void add(const Extrema &other)
Add the samples from the other Stats instance.
Definition Stats.h:130
openvdb::v11_0::math::Extrema::Extrema
Extrema()
Constructor.
Definition Stats.h:94
openvdb::v11_0::math::Extrema::mMax
double mMax
Definition Stats.h:166
openvdb::v11_0::math::Extrema::mSize
uint64_t mSize
Definition Stats.h:165
openvdb::v11_0::math::Extrema::range
double range() const
Return the range defined as the maximum value minus the minimum value.
Definition Stats.h:127
openvdb::v11_0::math::Extrema::min
double min() const
Return the minimum value.
Definition Stats.h:121
openvdb::v11_0::math::Extrema::size
uint64_t size() const
Return the size of the population, i.e., the total number of samples.
Definition Stats.h:118
openvdb::v11_0::math::Extrema::add
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition Stats.h:110
openvdb::v11_0::math::Extrema::join
void join(const Extrema &other)
Definition Stats.h:157
openvdb::v11_0::math::Extrema::mMin
double mMin
Definition Stats.h:166
openvdb::v11_0::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:136
openvdb::v11_0::math::Extrema::max
double max() const
Return the maximum value.
Definition Stats.h:124
openvdb::v11_0::math::Histogram
This class computes a histogram, with a fixed interval width, of a population of floating-point value...
Definition Stats.h:276
openvdb::v11_0::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:343
openvdb::v11_0::math::Histogram::count
uint64_t count(int n) const
Return the number of samples in the nth bin.
Definition Stats.h:338
openvdb::v11_0::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:308
openvdb::v11_0::math::Histogram::min
double min(int n) const
Return the minimum value in the nth bin.
Definition Stats.h:334
openvdb::v11_0::math::Histogram::min
double min() const
Return the lower bound of this histogram's value range.
Definition Stats.h:330
openvdb::v11_0::math::Histogram::size
uint64_t size() const
Return the population size, i.e., the total number of samples.
Definition Stats.h:340
openvdb::v11_0::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:293
openvdb::v11_0::math::Histogram::max
double max(int n) const
Return the maximum value in the nth bin.
Definition Stats.h:336
openvdb::v11_0::math::Histogram::numBins
size_t numBins() const
Return the number of bins in this histogram.
Definition Stats.h:328
openvdb::v11_0::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:318
openvdb::v11_0::math::Histogram::max
double max() const
Return the upper bound of this histogram's value range.
Definition Stats.h:332
openvdb::v11_0::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:279
openvdb::v11_0::math::MinMax
Templated class to compute the minimum and maximum values.
Definition Stats.h:31
openvdb::v11_0::math::MinMax::mMin
ValueType mMin
Definition Stats.h:83
openvdb::v11_0::math::MinMax::mMax
ValueType mMax
Definition Stats.h:83
openvdb::v11_0::math::MinMax::max
const ValueType & max() const
Return the maximum value.
Definition Stats.h:59
openvdb::v11_0::math::MinMax::add
void add(const ValueType &val, const Less &less=Less())
Add a single sample.
Definition Stats.h:49
openvdb::v11_0::math::MinMax::MinMax
MinMax(const ValueType &min, const ValueType &max)
Constructor.
Definition Stats.h:45
openvdb::v11_0::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:69
openvdb::v11_0::math::MinMax::MinMax
MinMax()
Empty constructor.
Definition Stats.h:38
openvdb::v11_0::math::MinMax::min
const ValueType & min() const
Return the minimum value.
Definition Stats.h:56
openvdb::v11_0::math::MinMax::add
void add(const MinMax &other, const Less &less=Less())
Add the samples from the other Stats instance.
Definition Stats.h:62
openvdb::v11_0::math::Stats
This class computes statistics (minimum value, maximum value, mean, variance and standard deviation) ...
Definition Stats.h:179
openvdb::v11_0::math::Stats::var
double var() const
Return the population variance.
Definition Stats.h:229
openvdb::v11_0::math::Stats::add
void add(double val)
Add a single sample.
Definition Stats.h:189
openvdb::v11_0::math::Stats::mAvg
double mAvg
Definition Stats.h:266
openvdb::v11_0::math::Stats::add
void add(const Stats &other)
Add the samples from the other Stats instance.
Definition Stats.h:208
openvdb::v11_0::math::Stats::mSize
uint64_t mSize
Definition Stats.h:165
openvdb::v11_0::math::Stats::mean
double mean() const
Definition Stats.h:222
openvdb::v11_0::math::Stats::variance
double variance() const
Definition Stats.h:230
openvdb::v11_0::math::Stats::add
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition Stats.h:198
openvdb::v11_0::math::Stats::stdDev
double stdDev() const
Definition Stats.h:237
openvdb::v11_0::math::Stats::mAux
double mAux
Definition Stats.h:266
openvdb::v11_0::math::Stats::std
double std() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance.
Definition Stats.h:236
openvdb::v11_0::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:241
openvdb::v11_0::math::Stats::avg
double avg() const
Return the arithmetic mean, i.e. average, value.
Definition Stats.h:221
openvdb::v11_0::math::Stats::Stats
Stats()
Definition Stats.h:181
openvdb::v11_0::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:589
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:212