Loading...
Searching...
No Matches
Stats.h
Go to the documentation of this file.
// Copyright Contributors to the OpenVDB Project
// SPDX-License-Identifier: MPL-2.0
//
/// @file Stats.h
///
/// @author Ken Museth
///
/// @brief Classes to compute statistics and histograms
#ifndef OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
#define OPENVDB_MATH_STATS_HAS_BEEN_INCLUDED
#include <iosfwd> // for ostringstream
#include <openvdb/version.h>
#include <openvdb/Exceptions.h>
#include <iostream>
#include <iomanip>
#include <sstream>
#include <vector>
#include <functional>// for std::less
#include "Math.h"
namespace openvdb {
OPENVDB_USE_VERSION_NAMESPACE
namespace OPENVDB_VERSION_NAME {
namespace math {
/// @brief Templated class to compute the minimum and maximum values.
template <typename ValueType, typename Less = std::less<ValueType> >
class MinMax
{
using Limits = std::numeric_limits<ValueType>;
public:
/// @brief Empty constructor
///
/// @warning Only use this constructor with POD types
MinMax() : mMin(Limits::max()), mMax(Limits::lowest())
{
static_assert(std::numeric_limits<ValueType>::is_specialized,
"openvdb::math::MinMax default constructor requires a std::numeric_limits specialization");
}
/// @brief Constructor
MinMax(const ValueType &min, const ValueType &max) : mMin(min), mMax(max)
{
}
/// @brief Default copy constructor
MinMax(const MinMax &other) = default;
/// Add a single sample.
inline void add(const ValueType &val, const Less &less = Less())
{
if (less(val, mMin)) mMin = val;
if (less(mMax, val)) mMax = val;
}
/// Return the minimum value.
inline const ValueType& min() const { return mMin; }
/// Return the maximum value.
inline const ValueType& max() const { return mMax; }
/// Add the samples from the other Stats instance.
inline void add(const MinMax& other, const Less &less = Less())
{
if (less(other.mMin, mMin)) mMin = other.mMin;
if (less(mMax, other.mMax)) mMax = other.mMax;
}
/// @brief Print MinMax to the specified output stream.
void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
{
// Write to a temporary string stream so as not to affect the state
// (precision, field width, etc.) of the output stream.
std::ostringstream os;
os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
os << "MinMax ";
if (!name.empty()) os << "for \"" << name << "\" ";
os << " Min=" << mMin << ", Max=" << mMax << std::endl;
strm << os.str();
}
protected:
ValueType mMin, mMax;
};//end MinMax
/// @brief This class computes the minimum and maximum values of a population
/// of floating-point values.
class Extrema
{
public:
/// @brief Constructor
/// @warning The min/max values are initiated to extreme values
Extrema()
: mSize(0)
, mMin(std::numeric_limits<double>::max())
, mMax(-mMin)
{
}
/// Add a single sample.
void add(double val)
{
++mSize;
mMin = std::min<double>(val, mMin);
mMax = std::max<double>(val, mMax);
}
/// Add @a n samples with constant value @a val.
void add(double val, uint64_t n)
{
mSize += n;
mMin = std::min<double>(val, mMin);
mMax = std::max<double>(val, mMax);
}
/// Return the size of the population, i.e., the total number of samples.
inline uint64_t size() const { return mSize; }
/// Return the minimum value.
inline double min() const { return mMin; }
/// Return the maximum value.
inline double max() const { return mMax; }
/// Return the range defined as the maximum value minus the minimum value.
inline double range() const { return mMax - mMin; }
/// Add the samples from the other Stats instance.
void add(const Extrema& other)
{
if (other.mSize > 0) this->join(other);
}
/// @brief Print extrema to the specified output stream.
void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
{
// Write to a temporary string stream so as not to affect the state
// (precision, field width, etc.) of the output stream.
std::ostringstream os;
os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
os << "Extrema ";
if (!name.empty()) os << "for \"" << name << "\" ";
if (mSize>0) {
os << "with " << mSize << " samples:\n"
<< " Min=" << mMin
<< ", Max=" << mMax
<< ", Range="<< this->range() << std::endl;
} else {
os << ": no samples were added." << std::endl;
}
strm << os.str();
}
protected:
inline void join(const Extrema& other)
{
assert(other.mSize > 0);
mSize += other.mSize;
mMin = std::min<double>(mMin, other.mMin);
mMax = std::max<double>(mMax, other.mMax);
}
uint64_t mSize;
double mMin, mMax;
};//end Extrema
/// @brief This class computes statistics (minimum value, maximum
/// value, mean, variance and standard deviation) of a population
/// of floating-point values.
///
/// @details variance = Mean[ (X-Mean[X])^2 ] = Mean[X^2] - Mean[X]^2,
/// standard deviation = sqrt(variance)
///
/// @note This class employs incremental computation and double precision.
class Stats : public Extrema
{
public:
Stats()
: Extrema()
, mAvg(0.0)
, mAux(0.0)
{
}
/// Add a single sample.
void add(double val)
{
Extrema::add(val);
const double delta = val - mAvg;
mAvg += delta/double(mSize);
mAux += delta*(val - mAvg);
}
/// Add @a n samples with constant value @a val.
void add(double val, uint64_t n)
{
const double denom = 1.0/double(mSize + n);
const double delta = val - mAvg;
mAvg += denom * delta * double(n);
mAux += denom * delta * delta * double(mSize) * double(n);
Extrema::add(val, n);
}
/// Add the samples from the other Stats instance.
void add(const Stats& other)
{
if (other.mSize > 0) {
const double denom = 1.0/double(mSize + other.mSize);
const double delta = other.mAvg - mAvg;
mAvg += denom * delta * double(other.mSize);
mAux += other.mAux + denom * delta * delta * double(mSize) * double(other.mSize);
Extrema::join(other);
}
}
//@{
/// Return the arithmetic mean, i.e. average, value.
inline double avg() const { return mAvg; }
inline double mean() const { return mAvg; }
//@}
//@{
/// @brief Return the population variance.
/// @note The unbiased sample variance = population variance *
//num/(num-1)
inline double var() const { return mSize<2 ? 0.0 : mAux/double(mSize); }
inline double variance() const { return this->var(); }
//@}
//@{
/// @brief Return the standard deviation (=Sqrt(variance)) as
/// defined from the (biased) population variance.
inline double std() const { return sqrt(this->var()); }
inline double stdDev() const { return this->std(); }
//@}
/// @brief Print statistics to the specified output stream.
void print(const std::string &name= "", std::ostream &strm=std::cout, int precision=3) const
{
// Write to a temporary string stream so as not to affect the state
// (precision, field width, etc.) of the output stream.
std::ostringstream os;
os << std::setprecision(precision) << std::setiosflags(std::ios::fixed);
os << "Statistics ";
if (!name.empty()) os << "for \"" << name << "\" ";
if (mSize>0) {
os << "with " << mSize << " samples:\n"
<< " Min=" << mMin
<< ", Max=" << mMax
<< ", Ave=" << mAvg
<< ", Std=" << this->stdDev()
<< ", Var=" << this->variance() << std::endl;
} else {
os << ": no samples were added." << std::endl;
}
strm << os.str();
}
protected:
using Extrema::mSize;
using Extrema::mMin;
using Extrema::mMax;
double mAvg, mAux;
}; // end Stats
////////////////////////////////////////
/// @brief This class computes a histogram, with a fixed interval width,
/// of a population of floating-point values.
class Histogram
{
public:
/// Construct with given minimum and maximum values and the given bin count.
Histogram(double min, double max, size_t numBins = 10)
: mSize(0), mMin(min), mMax(max + 1e-10),
mDelta(double(numBins)/(max-min)), mBins(numBins)
{
if ( mMax <= mMin ) {
OPENVDB_THROW(ValueError, "Histogram: expected min < max");
} else if ( numBins == 0 ) {
OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
}
for (size_t i=0; i<numBins; ++i) mBins[i]=0;
}
/// @brief Construct with the given bin count and with minimum and maximum values
/// taken from a Stats object.
Histogram(const Stats& s, size_t numBins = 10):
mSize(0), mMin(s.min()), mMax(s.max()+1e-10),
mDelta(double(numBins)/(mMax-mMin)), mBins(numBins)
{
if ( mMax <= mMin ) {
OPENVDB_THROW(ValueError, "Histogram: expected min < max");
} else if ( numBins == 0 ) {
OPENVDB_THROW(ValueError, "Histogram: expected at least one bin");
}
for (size_t i=0; i<numBins; ++i) mBins[i]=0;
}
/// @brief Add @a n samples with constant value @a val, provided that the
/// @a val falls within this histogram's value range.
/// @return @c true if the sample value falls within this histogram's value range.
inline bool add(double val, uint64_t n = 1)
{
if (val<mMin || val>mMax) return false;
mBins[size_t(mDelta*(val-mMin))] += n;
mSize += n;
return true;
}
/// @brief Add all the contributions from the other histogram, provided that
/// it has the same configuration as this histogram.
bool add(const Histogram& other)
{
if (!isApproxEqual(mMin, other.mMin) || !isApproxEqual(mMax, other.mMax) ||
mBins.size() != other.mBins.size()) return false;
for (size_t i=0, e=mBins.size(); i!=e; ++i) mBins[i] += other.mBins[i];
mSize += other.mSize;
return true;
}
/// Return the number of bins in this histogram.
inline size_t numBins() const { return mBins.size(); }
/// Return the lower bound of this histogram's value range.
inline double min() const { return mMin; }
/// Return the upper bound of this histogram's value range.
inline double max() const { return mMax; }
/// Return the minimum value in the <i>n</i>th bin.
inline double min(int n) const { return mMin+n/mDelta; }
/// Return the maximum value in the <i>n</i>th bin.
inline double max(int n) const { return mMin+(n+1)/mDelta; }
/// Return the number of samples in the <i>n</i>th bin.
inline uint64_t count(int n) const { return mBins[n]; }
/// Return the population size, i.e., the total number of samples.
inline uint64_t size() const { return mSize; }
/// Print the histogram to the specified output stream.
void print(const std::string& name = "", std::ostream& strm = std::cout) const
{
// Write to a temporary string stream so as not to affect the state
// (precision, field width, etc.) of the output stream.
std::ostringstream os;
os << std::setprecision(6) << std::setiosflags(std::ios::fixed) << std::endl;
os << "Histogram ";
if (!name.empty()) os << "for \"" << name << "\" ";
if (mSize > 0) {
os << "with " << mSize << " samples:\n";
os << "==============================================================\n";
os << "|| # | Min | Max | Frequency | % ||\n";
os << "==============================================================\n";
for (int i = 0, e = int(mBins.size()); i != e; ++i) {
os << "|| " << std::setw(4) << i << " | " << std::setw(14) << this->min(i) << " | "
<< std::setw(14) << this->max(i) << " | " << std::setw(9) << mBins[i] << " | "
<< std::setw(3) << (100*mBins[i]/mSize) << " ||\n";
}
os << "==============================================================\n";
} else {
os << ": no samples were added." << std::endl;
}
strm << os.str();
}
private:
uint64_t mSize;
double mMin, mMax, mDelta;
std::vector<uint64_t> mBins;
};// end Histogram
} // namespace math
} // namespace OPENVDB_VERSION_NAME
} // namespace openvdb
#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::v10_0::ValueError
Definition Exceptions.h:65
openvdb::v10_0::math::Extrema::add
void add(double val)
Add a single sample.
Definition Stats.h:106
openvdb::v10_0::math::Extrema::add
void add(const Extrema &other)
Add the samples from the other Stats instance.
Definition Stats.h:134
openvdb::v10_0::math::Extrema::Extrema
Extrema()
Constructor.
Definition Stats.h:98
openvdb::v10_0::math::Extrema::mMax
double mMax
Definition Stats.h:170
openvdb::v10_0::math::Extrema::mSize
uint64_t mSize
Definition Stats.h:169
openvdb::v10_0::math::Extrema::range
double range() const
Return the range defined as the maximum value minus the minimum value.
Definition Stats.h:131
openvdb::v10_0::math::Extrema::min
double min() const
Return the minimum value.
Definition Stats.h:125
openvdb::v10_0::math::Extrema::size
uint64_t size() const
Return the size of the population, i.e., the total number of samples.
Definition Stats.h:122
openvdb::v10_0::math::Extrema::add
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition Stats.h:114
openvdb::v10_0::math::Extrema::join
void join(const Extrema &other)
Definition Stats.h:161
openvdb::v10_0::math::Extrema::mMin
double mMin
Definition Stats.h:170
openvdb::v10_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:140
openvdb::v10_0::math::Extrema::max
double max() const
Return the maximum value.
Definition Stats.h:128
openvdb::v10_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:347
openvdb::v10_0::math::Histogram::count
uint64_t count(int n) const
Return the number of samples in the nth bin.
Definition Stats.h:342
openvdb::v10_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:312
openvdb::v10_0::math::Histogram::min
double min(int n) const
Return the minimum value in the nth bin.
Definition Stats.h:338
openvdb::v10_0::math::Histogram::min
double min() const
Return the lower bound of this histogram's value range.
Definition Stats.h:334
openvdb::v10_0::math::Histogram::size
uint64_t size() const
Return the population size, i.e., the total number of samples.
Definition Stats.h:344
openvdb::v10_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:297
openvdb::v10_0::math::Histogram::max
double max(int n) const
Return the maximum value in the nth bin.
Definition Stats.h:340
openvdb::v10_0::math::Histogram::numBins
size_t numBins() const
Return the number of bins in this histogram.
Definition Stats.h:332
openvdb::v10_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:322
openvdb::v10_0::math::Histogram::max
double max() const
Return the upper bound of this histogram's value range.
Definition Stats.h:336
openvdb::v10_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:283
openvdb::v10_0::math::MinMax::mMin
ValueType mMin
Definition Stats.h:87
openvdb::v10_0::math::MinMax::MinMax
MinMax(const MinMax &other)=default
Default copy constructor.
openvdb::v10_0::math::MinMax::mMax
ValueType mMax
Definition Stats.h:87
openvdb::v10_0::math::MinMax::max
const ValueType & max() const
Return the maximum value.
Definition Stats.h:63
openvdb::v10_0::math::MinMax::add
void add(const ValueType &val, const Less &less=Less())
Add a single sample.
Definition Stats.h:53
openvdb::v10_0::math::MinMax::MinMax
MinMax(const ValueType &min, const ValueType &max)
Constructor.
Definition Stats.h:45
openvdb::v10_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:73
openvdb::v10_0::math::MinMax::MinMax
MinMax()
Empty constructor.
Definition Stats.h:38
openvdb::v10_0::math::MinMax::min
const ValueType & min() const
Return the minimum value.
Definition Stats.h:60
openvdb::v10_0::math::MinMax::add
void add(const MinMax &other, const Less &less=Less())
Add the samples from the other Stats instance.
Definition Stats.h:66
openvdb::v10_0::math::Stats
This class computes statistics (minimum value, maximum value, mean, variance and standard deviation) ...
Definition Stats.h:183
openvdb::v10_0::math::Stats::var
double var() const
Return the population variance.
Definition Stats.h:233
openvdb::v10_0::math::Stats::add
void add(double val)
Add a single sample.
Definition Stats.h:193
openvdb::v10_0::math::Stats::mAvg
double mAvg
Definition Stats.h:270
openvdb::v10_0::math::Stats::mMax
double mMax
Definition Stats.h:170
openvdb::v10_0::math::Stats::add
void add(const Stats &other)
Add the samples from the other Stats instance.
Definition Stats.h:212
openvdb::v10_0::math::Stats::mSize
uint64_t mSize
Definition Stats.h:169
openvdb::v10_0::math::Stats::mean
double mean() const
Definition Stats.h:226
openvdb::v10_0::math::Stats::variance
double variance() const
Definition Stats.h:234
openvdb::v10_0::math::Stats::add
void add(double val, uint64_t n)
Add n samples with constant value val.
Definition Stats.h:202
openvdb::v10_0::math::Stats::stdDev
double stdDev() const
Definition Stats.h:241
openvdb::v10_0::math::Stats::mAux
double mAux
Definition Stats.h:270
openvdb::v10_0::math::Stats::mMin
double mMin
Definition Stats.h:170
openvdb::v10_0::math::Stats::std
double std() const
Return the standard deviation (=Sqrt(variance)) as defined from the (biased) population variance.
Definition Stats.h:240
openvdb::v10_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:245
openvdb::v10_0::math::Stats::avg
double avg() const
Return the arithmetic mean, i.e. average, value.
Definition Stats.h:225
openvdb::v10_0::math::Stats::Stats
Stats()
Definition Stats.h:185
openvdb::v10_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:587
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