Auxiliary data structure for running average, standard deviation and quantiles. More...

#include <JQuantile.hh>

Inheritance diagram for JTOOLS::JQuantile:

Public Types
enum	Quantile_t { forward_t = +1, symmetric_t = 0, backward_t = -1 }
	Options for evaluation of quantile. More...

Public Member Functions
	JQuantile (const JTitle &title="", const bool quantiles=false)
	Constructor. More...

template<class JElement_t , class JAllocator_t >
	JQuantile (const JTitle &title, const array_type< JElement_t, JAllocator_t > &buffer, const bool quantiles=false, const double w=1.0)
	Constructor. More...

void	reset ()
	Reset. More...

JQuantile &	add (const JQuantile &Q)
	Add quantile. More...

void	put (const double x, const double w=1.0)
	Put value. More...

template<class JElement_t , class JAllocator_t >
void	put (const array_type< JElement_t, JAllocator_t > &buffer, const double w=1.0)
	Put data. More...

long long int	getCount () const
	Get total count. More...

double	getTotal () const
	Get total weight. More...

double	getXmin () const
	Get minimum value. More...

double	getXmax () const
	Get maximum value. More...

double	getWmin () const
	Get minimum weight. More...

double	getWmax () const
	Get maximum weight. More...

double	getMean () const
	Get mean value. More...

double	getSTDev () const
	Get standard deviation. More...

double	getDeviation (const bool relative=true) const
	Get maximal deviation from average. More...

bool	hasAccuracy (const double precision) const
	Test relative accuracy. More...

double	getQuantile (const double Q, const Quantile_t option=forward_t) const
	Get quantile. More...

std::ostream &	print (std::ostream &out, bool lpr=true) const
	Print quantile. More...

const std::string &	getTitle () const
	Get title. More...

void	setTitle (const std::string &title)
	Set title. More...

JFirst_t &	mul (const JSecond_t &object)
	Multiply with object. More...

Static Protected Member Functions
template<class T >
static double	getQuantile (T __begin, T __end, const double W)
	Get quantile. More...

Protected Attributes
bool	quantiles

double	mean

double	sigma

double	total

long long int	count

double	xmin

double	xmax

double	wmin

double	wmax

std::multimap< double, double >	buffer

std::string	title

Friends
std::ostream &	operator<< (std::ostream &out, const JQuantile &quantile)
	Print quantile. More...

Detailed Description

Auxiliary data structure for running average, standard deviation and quantiles.

See Knuth TAOCP vol 2, 3rd edition, page 232.
This class acts as a zero-dimensional histogram.
Note that if a weight is used, it should strictly be positive.

Definition at line 43 of file JQuantile.hh.

Member Enumeration Documentation

enum JTOOLS::JQuantile::Quantile_t

Options for evaluation of quantile.

Enumerator
forward_t	forward
symmetric_t	symmatric
backward_t	backward

Definition at line 305 of file JQuantile.hh.

                     {
       forward_t    = +1,     //!< forward
       symmetric_t  =  0,     //!< symmatric
       backward_t   = -1      //!< backward
     };

Constructor & Destructor Documentation

JTOOLS::JQuantile::JQuantile	(	const JTitle &	title = `""`,
		const bool	quantiles = `false`
	)

inline

Constructor.

Parameters

title	title
quantiles	quantiles

Definition at line 53 of file JQuantile.hh.

                                                :
       JTitle(title),
       quantiles(quantiles)
     {
       reset();
     }

template<class JElement_t , class JAllocator_t >

JTOOLS::JQuantile::JQuantile	(	const JTitle &	title,
		const array_type< JElement_t, JAllocator_t > &	buffer,
		const bool	quantiles = `false`,
		const double	w = `1.0`
	)

inline

Constructor.

Parameters

title	title
buffer	input data
quantiles	quantiles
w	weight

Definition at line 71 of file JQuantile.hh.

                                              :
       JTitle(title),
       quantiles(quantiles)
     {
       reset();
 
       put(buffer, w);
     }

Member Function Documentation

void JTOOLS::JQuantile::reset ( )

inline

Reset.

Definition at line 87 of file JQuantile.hh.

     {
       mean  = 0.0;
       sigma = 0.0;
       total = 0.0;
       count = 0;
       xmin  = std::numeric_limits<double>::max();
       xmax  = std::numeric_limits<double>::lowest();
       wmin  = std::numeric_limits<double>::max();
       wmax  = std::numeric_limits<double>::lowest();
 
       buffer.clear();
     }

JQuantile& JTOOLS::JQuantile::add ( const JQuantile & Q )

inline

Add quantile.

Parameters

Q quantile

Returns: this quantile

Definition at line 108 of file JQuantile.hh.

     {
       mean  += Q.mean;
       sigma += Q.sigma;
       total += Q.total;
       count += Q.count;
       xmin   = std::min(xmin, Q.xmin);
       xmax   = std::max(xmax, Q.xmax);
       wmin   = std::min(wmin, Q.wmin);
       wmax   = std::max(wmax, Q.wmax);
 
       if (quantiles) {
         std::copy(Q.buffer.begin(), Q.buffer.end(), std::inserter(buffer, buffer.end()));
       }
 
       return *this;
     }

void JTOOLS::JQuantile::put	(	const double	x,
		const double	w = `1.0`
	)

inline

Put value.

Parameters

x	value
w	weight

Definition at line 133 of file JQuantile.hh.

     {
       total += w;
       count += 1;
 
       if (count == 1) {
 
         mean  = x;
         sigma = 0.0;
 
       } else {
 
         const double new_mean  = mean   +  w * (x - mean) / total;
         const double new_sigma = sigma  +  w * (x - mean) * (x - new_mean);
     
         // set up for next iteration
 
         mean  = new_mean; 
         sigma = new_sigma;
       }
 
       xmin = std::min(xmin, x);
       xmax = std::max(xmax, x);
       wmin = std::min(wmin, w);
       wmax = std::max(wmax, w);
 
       if (quantiles) {
         buffer.insert(std::make_pair(x,w));
       }
     }

template<class JElement_t , class JAllocator_t >

void JTOOLS::JQuantile::put	(	const array_type< JElement_t, JAllocator_t > &	buffer,
		const double	w = `1.0`
	)

inline

Put data.

Parameters

buffer	input data
w	weight

Definition at line 172 of file JQuantile.hh.

     {
       for (typename array_type<JElement_t, JAllocator_t>::const_iterator i = buffer.begin(); i != buffer.end(); ++i) {
         put(*i, w);
       }
     }

long long int JTOOLS::JQuantile::getCount ( ) const

inline

Get total count.

Returns: count

Definition at line 186 of file JQuantile.hh.

     {
       return count;
     }

double JTOOLS::JQuantile::getTotal ( ) const

inline

Get total weight.

Returns: weight

Definition at line 197 of file JQuantile.hh.

     {
       return total;
     }

double JTOOLS::JQuantile::getXmin ( ) const

inline

Get minimum value.

Returns: minimum value

Definition at line 208 of file JQuantile.hh.

     {
       return xmin;
     }

double JTOOLS::JQuantile::getXmax ( ) const

inline

Get maximum value.

Returns: maximum value

Definition at line 219 of file JQuantile.hh.

     {
       return xmax;
     }

double JTOOLS::JQuantile::getWmin ( ) const

inline

Get minimum weight.

Returns: minimum weight

Definition at line 230 of file JQuantile.hh.

     {
       return wmin;
     }

double JTOOLS::JQuantile::getWmax ( ) const

inline

Get maximum weight.

Returns: maximum weight

Definition at line 241 of file JQuantile.hh.

     {
       return wmax;
     }

double JTOOLS::JQuantile::getMean ( ) const

inline

Get mean value.

Returns: mean value

Definition at line 252 of file JQuantile.hh.

     {
       if (count != 0.0)
         return mean;
       else
         THROW(JDivisionByZero, "JQuantile::getMean()");
     }

double JTOOLS::JQuantile::getSTDev ( ) const

inline

Get standard deviation.

Returns: standard deviation

Definition at line 266 of file JQuantile.hh.

     {
       if (count > 1)
         return sqrt(count * sigma/(total * (count - 1)));
       else
         THROW(JDivisionByZero, "JQuantile::getSTDev()");
     }

double JTOOLS::JQuantile::getDeviation ( const bool relative = true ) const

inline

Get maximal deviation from average.

Parameters

relative if true, relative to average, else absolute

Returns: deviation

Definition at line 281 of file JQuantile.hh.

     {
       if (relative)
         return std::max(getXmax() - getMean(), getMean() - getXmin());
       else
         return getXmax() - getXmin();
     }

bool JTOOLS::JQuantile::hasAccuracy ( const double precision ) const

inline

Test relative accuracy.

Parameters

precision relative precision

Returns: true if reached accuracy; else false

Definition at line 296 of file JQuantile.hh.

     {
       return getCount() > 1 && getSTDev() < precision * getMean();
     }

double JTOOLS::JQuantile::getQuantile	(	const double	Q,
		const Quantile_t	option = `forward_t`
	)		const

inline

Get quantile.

Parameters

Q	quantile
option	option

Returns: value

Definition at line 319 of file JQuantile.hh.

     {
       if (quantiles) {
 
         double W = 0.0;
 
         for (std::map<double, double>::const_iterator i = buffer.begin(); i != buffer.end(); ++i) {
           W += i->second;
         }
 
         switch (option) {
         case forward_t:
           return (getQuantile(buffer. begin(), buffer. end(), Q*W));
         case symmetric_t:
           return (getQuantile(buffer.rbegin(), buffer.rend(), 0.5*(1.0 - Q)*W)  -
                   getQuantile(buffer. begin(), buffer. end(), 0.5*(1.0 - Q)*W));
         case backward_t:
           return (getQuantile(buffer.rbegin(), buffer.rend(), Q*W));
         default:
           THROW(JNoValue, "Invalid option " << option);
         }
       }
 
       THROW(JNoValue, "Option 'quantiles' at JQuantile() incompatible with method getQuantile().");
     }

std::ostream& JTOOLS::JQuantile::print	(	std::ostream &	out,
		bool	lpr = `true`
	)		const

inline

Print quantile.

Parameters

out	output stream
lpr	long print

Definition at line 352 of file JQuantile.hh.

     {
       using namespace std;
 
       const int nc = getTitle().size();
 
       if (lpr) {
         out << setw(nc) << left  << " "             << ' '
             << setw(12) << left  << "    mean"      << ' '
             << setw(12) << left  << "    STD"       << ' '
             << setw(12) << left  << "  deviation"   << endl;
       }
 
       out << setw(nc) << left << getTitle()          << ' '
           << SCIENTIFIC(12,5) << getMean()           << ' '
           << SCIENTIFIC(12,5) << getSTDev()          << ' '
           << SCIENTIFIC(12,5) << getDeviation(false) << endl;
 
       return out;
     }

template<class T >

static double JTOOLS::JQuantile::getQuantile	(	T	__begin,
		T	__end,
		const double	W
	)

inlinestaticprotected

Get quantile.

Parameters

__begin	begin of data
__end	end of data
W	weight

Returns: value

Definition at line 396 of file JQuantile.hh.

     {
       double w = 0.0;
 
       for (T i = __begin; i != __end; ++i) {
 
         w += i->second;
 
         if (w >= W) {
           return i->first;
         }
       }
 
       THROW(JNoValue, "Invalid weight " << W);
     }

const std::string& JLANG::JTitle::getTitle ( ) const

inlineinherited

Get title.

Returns: title

Definition at line 55 of file JTitle.hh.

     {
       return this->title;
     }

void JLANG::JTitle::setTitle ( const std::string & title )

inlineinherited

Set title.

Parameters

title title

Definition at line 66 of file JTitle.hh.

     {
       this->title = title;
     }

template<class JFirst_t, class JSecond_t = JNullType>

JFirst_t& JMATH::JMath< JFirst_t, JSecond_t >::mul ( const JSecond_t & object )

inlineinherited

Multiply with object.

Parameters

object object

Returns: result object

Definition at line 354 of file JMath.hh.

     {
       return static_cast<JFirst_t&>(*this) = JFirst_t().mul(static_cast<const JFirst_t&>(*this), object);
     }

Friends And Related Function Documentation

std::ostream& operator<<	(	std::ostream &	out,
		const JQuantile &	quantile
	)

friend

Print quantile.

Parameters

out	output stream
quantile	quantile

Returns: output stream

Definition at line 381 of file JQuantile.hh.

     {
       return quantile.print(out, getLongprint(out));
     }

Member Data Documentation

bool JTOOLS::JQuantile::quantiles

protected

Definition at line 413 of file JQuantile.hh.

double JTOOLS::JQuantile::mean

protected

Definition at line 414 of file JQuantile.hh.

double JTOOLS::JQuantile::sigma

protected

Definition at line 415 of file JQuantile.hh.

double JTOOLS::JQuantile::total

protected

Definition at line 416 of file JQuantile.hh.

long long int JTOOLS::JQuantile::count

protected

Definition at line 417 of file JQuantile.hh.

double JTOOLS::JQuantile::xmin

protected

Definition at line 418 of file JQuantile.hh.

double JTOOLS::JQuantile::xmax

protected

Definition at line 419 of file JQuantile.hh.

double JTOOLS::JQuantile::wmin

protected

Definition at line 420 of file JQuantile.hh.

double JTOOLS::JQuantile::wmax

protected

Definition at line 421 of file JQuantile.hh.

std::multimap<double, double> JTOOLS::JQuantile::buffer

protected

Definition at line 422 of file JQuantile.hh.

std::string JLANG::JTitle::title

protectedinherited

Definition at line 73 of file JTitle.hh.

The documentation for this struct was generated from the following file:

JQuantile.hh

Public Types

Public Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation