theoretica::histogram Class Reference

Histogram class with running statistics, can be constructed from the parameters of the bins or from a dataset. More...

#include <histogram.h>

Public Member Functions
	histogram ()=default
	Default constructor, creates an empty histogram with no bins and NaN range.
	histogram (unsigned int bin_count, real range_min, real range_max)
	Construct the histogram from the number of bins and the range.
template<typename Dataset , enable_vector< Dataset > = true>
	histogram (const Dataset &data, unsigned int bin_count=0)
	Construct the histogram from a set of data points, with the given number of bins.
void	insert (real x)
	Insert a new data point inside the histogram, updating the running statistics and the corresponding bin.
unsigned int	index (real x) const
	Find the bin index corresponding to a given data point.
vec2	range () const
	Get the histogram range as a vector of two elements, containing the lower and upper extremes.
unsigned int	number () const
	Get the number of data points inside the histogram.
std::vector< unsigned int >	bins () const
	Get a vector containing the bin counts of each bin.
real	range_lower () const
	Return the lower extreme of the histogram range.
real	range_upper () const
	Return the upper extreme of the histogram range.
real	max () const
	Get the biggest data point of the histogram.
real	min () const
	Get the smallest data point of the histogram.
real	mean () const
	Get the mean value of the histogram data.
real	tss () const
	Get the total sum of squares (TSS) computed using Welford's one-pass method.
void	rebuild (const std::vector< unsigned int > &bin_counts, const vec2 &range, size_t N, real run_average, real run_tss, real value_min, real value_max)
	Rebuild the histogram from its parameters, including the bin counts and the running statistics (used for file IO).
real	operator() (real x)
	Evaluate the histogram like a step function which is zero outside the range of the histogram.
unsigned int	operator[] (unsigned int i) const
	Get the number of elements in the i-th bin.
std::string	to_string (const std::string &separator=" ", bool normalized=true, bool lower_extreme=false) const
	Convert the histogram to string representation.
	operator std::string ()
	Convert the histogram to string representation.

Friends
std::ostream &	operator<< (std::ostream &out, const histogram &obj)
	Stream the histogram in string representation to an output stream (std::ostream)

Detailed Description

Histogram class with running statistics, can be constructed from the parameters of the bins or from a dataset.

Elements are inserted one by one, updating the running statistics for the TSS, mean, maximum and minimum on each step.

Constructor & Destructor Documentation

histogram() [1/3]

theoretica::histogram::histogram ( )

default

Default constructor, creates an empty histogram with no bins and NaN range.

Make sure to set the range and bins before inserting any data point, otherwise the histogram will not work as intended.

histogram() [2/3]

theoretica::histogram::histogram ( unsigned int  bin_count, real  range_min, real  range_max  )

inline

Construct the histogram from the number of bins and the range.

The histogram is initialized from the arguments, without specifying any data points, which need to be added with insert().

Parameters

bin_count	The number of bins
range_min	The lower bound of the range
range_max	The upper bound of the range

histogram() [3/3]

template<typename Dataset , enable_vector< Dataset > = true>

theoretica::histogram::histogram ( const Dataset &  data, unsigned int  bin_count = 0  )

inline

Construct the histogram from a set of data points, with the given number of bins.

If the number of bins is not specified, it defaults to \([\sqrt{N}]\).

Parameters

data	The set of data points
bin_count	The number of bins (defaults to the square root of the number of points)

Member Function Documentation

bins()

std::vector< unsigned int > theoretica::histogram::bins ( ) const

inline

Get a vector containing the bin counts of each bin.

Note

The bins cannot be directly modified, new elements must be added using insert().

Returns

A vector containing the number of elements in each bin.

index()

unsigned int theoretica::histogram::index ( real  x ) const

inline

Find the bin index corresponding to a given data point.

Parameters

x	The value to find the bin index of (must be between range_min and range_max)

Note

This function does not check whether the value is between range_min and range_max, so care should be taken to use only valid inputs.

insert()

void theoretica::histogram::insert ( real  x )

inline

Insert a new data point inside the histogram, updating the running statistics and the corresponding bin.

Parameters

x	The value to insert

max()

real theoretica::histogram::max ( ) const

inline

Get the biggest data point of the histogram.

Returns

The maximum value of all elements.

mean()

real theoretica::histogram::mean ( ) const

inline

Get the mean value of the histogram data.

Returns

The running mean of all elements of the histogram.

min()

real theoretica::histogram::min ( ) const

inline

Get the smallest data point of the histogram.

Returns

The minimum value of all elements.

number()

unsigned int theoretica::histogram::number ( ) const

inline

Get the number of data points inside the histogram.

Returns

The number of data points which have been added to the histogram.

operator()()

real theoretica::histogram::operator() ( real  x )

inline

Evaluate the histogram like a step function which is zero outside the range of the histogram.

Parameters

x	The point to evaluate the histogram function at

Returns

The value of the histogram function at x

operator[]()

unsigned int theoretica::histogram::operator[] ( unsigned int  i ) const

inline

Get the number of elements in the i-th bin.

Parameters

i	The index of the bin

Returns

The number of elements in the i-th bin

range()

vec2 theoretica::histogram::range ( ) const

inline

Get the histogram range as a vector of two elements, containing the lower and upper extremes.

Returns

A vector containing the lower extreme of the histogram range as first element and the upper extreme as second element (accessible with [0] and [1]).

to_string()

std::string theoretica::histogram::to_string ( const std::string &  separator = " ", bool  normalized = true, bool  lower_extreme = false  ) const

inline

Convert the histogram to string representation.

Parameters

separator	The string to print between row elements
normalized	Whether to normalize the bin counts as a frequency (defaults to true).
lower_extreme	Whether to print the lower extreme of the bins or use the mid point (defaults to false, using mid points).

Returns

A string representing the histogram, ready to plot.

tss()

real theoretica::histogram::tss ( ) const

inline

Get the total sum of squares (TSS) computed using Welford's one-pass method.

Returns

The total sum of squares of all elements of the histogram.

---

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

• statistics/histogram.h