#include <Basics.h>

Public Member Functions
	Hist ()
	Constructors, including copy constructors.

	Hist (string titleIn, int nBinIn=100, double xMinIn=0., double xMaxIn=1., bool logXIn=false, bool doStatsIn=false)

	Hist (const Hist &h)

	Hist (string titleIn, const Hist &h)

Hist &	operator= (const Hist &h)

void	book (string titleIn=" ", int nBinIn=100, double xMinIn=0., double xMaxIn=1., bool logXIn=false, bool doStatsIn=false)
	Book a histogram.

void	title (string titleIn=" ")
	Set title of a histogram.

void	null ()
	Reset bin contents.

void	fill (double x, double w=1.)
	Fill bin with weight. More...

void	table (ostream &os=cout, bool printOverUnder=false, bool xMidBin=true, bool printError=false) const
	Print histogram contents as a table (e.g. for Gnuplot). More...

void	table (string fileName, bool printOverUnder=false, bool xMidBin=true, bool printError=false) const

void	rivetTable (ostream &os=cout, bool printError=true) const
	Print histogram contents as a table, in Rivet's *.dat style. More...

void	rivetTable (string fileName, bool printError=true) const

void	pyplotTable (ostream &os=cout, bool isHist=true, bool printError=false) const
	Print histogram contents as a table, as appropriate for Pyplot. More...

void	pyplotTable (string fileName, bool isHist=true, bool printError=false) const

void	fillTable (istream &is=cin)
	Fill contents of a two-column (x,y) table, e.g. written by table() above. More...

void	fillTable (string fileName)

string	getTitle () const
	Return title and size of histogram. Also if logarithmic x scale.

int	getBinNumber () const

int	getNonFinite () const

bool	getLinX () const

double	getXMin () const
	Return min and max in x and y directions.

double	getXMax () const

double	getYMin () const

double	getYMax () const

double	getYAbsMin () const

double	getXMean (bool unbinned=true) const
	Compute mean value in X, by default unbinned. More...

double	getXMeanErr (bool unbinned=true) const
	Error on mean value. More...

double	getXMedian (bool includeOverUnder=false) const

double	getXMedianErr (bool unbinned=true) const

double	getYMean () const
	Return average <Y> value.

double	getXRMN (int n=2, bool unbinned=true) const

double	getXRMS (bool unbinned=true) const

double	getXRMNErr (int n=2, bool unbinned=true) const

double	getXRMSErr (bool unbinned=true) const

double	getBinContent (int iBin) const
	Return content of specific bin: 0 gives underflow and nBin+1 overflow. More...

double	getBinEdge (int iBin) const
	Return the lower edge of the bin.

double	getBinWidth (int iBin=1) const
	Return the width of the bin.

vector< double >	getBinContents () const
	Return bin contents. More...

vector< double >	getBinEdges () const
	Return bin edges.

int	getEntries (bool alsoNonFinite=true) const
	Return number of entries.

double	getWeightSum (bool alsoOverUnder=true) const
	Return sum of weights.

double	getNEffective () const

bool	sameSize (const Hist &h) const
	Check whether another histogram has same size and limits.

void	takeFunc (function< double(double)> func)
	Take an arbitrary function of bin contents. More...

void	takeLog (bool tenLog=true)
	Take logarithm (base 10 or e) of bin contents. More...

void	takeSqrt ()
	Take square root of bin contents. More...

void	normalize (double f=1, bool overflow=true)
	Normalize sum of bin contents to value, with or without overflow bins. More...

void	normalizeIntegral (double f=1, bool overflow=true)
	Normalize sum of bin areas to value, with or without overflow bins. More...

void	normalizeSpectrum (double wtSum)
	Scale each bin content by 1 / (wtSum * bin width).

Hist &	operator+= (const Hist &h)
	Operator overloading with member functions. More...

Hist &	operator-= (const Hist &h)
	Subtract histogram from existing one.

Hist &	operator*= (const Hist &h)

Hist &	operator/= (const Hist &h)

Hist &	operator+= (double f)

Hist &	operator-= (double f)

Hist &	operator*= (double f)
	Multiply histogram by constant.

Hist &	operator/= (double f)
	Divide histogram by constant. More...

Hist	operator+ (double f) const

Hist	operator+ (const Hist &h2) const

Hist	operator- (double f) const

Hist	operator- (const Hist &h2) const

Hist	operator* (double f) const

Hist	operator* (const Hist &h2) const

Hist	operator/ (double f) const

Hist	operator/ (const Hist &h2) const

Static Public Member Functions
static Hist	plotFunc (function< double(double)> f, string titleIn, int nBinIn, double xMinIn, double xMaxIn, bool logXIn=false)
	Create a histogram that is the plot of the given function.

Friends
ostream &	operator<< (ostream &os, const Hist &h)
	Print a histogram with overloaded << operator. More...

void	table (const Hist &h1, const Hist &h2, ostream &os, bool printOverUnder, bool xMidBin)
	Print a table out of two histograms with same x axis (no errors printed). More...

void	table (const Hist &h1, const Hist &h2, string fileName, bool printOverUnder, bool xMidBin)

Hist	operator+ (double f, const Hist &h1)
	Operator overloading with friends. More...

Hist	operator- (double f, const Hist &h1)

Hist	operator* (double f, const Hist &h1)

Hist	operator/ (double f, const Hist &h1)

Detailed Description

Hist class. This class handles a single histogram at a time.

Member Function Documentation

void fill	(	double	x,
		double	w = `1.`
	)

Fill bin with weight.

If requested, also compute unbinned higher moments.

void fillTable ( istream & is = cin )

Fill contents of a two-column (x,y) table, e.g. written by table() above.

Fill histogram contents from a table, e.g. written by table() above.

Read in one line at a time.

Read contents of the line and fill in histogram.

double getBinContent ( int iBin ) const

Return content of specific bin: 0 gives underflow and nBin+1 overflow.

Get content of specific bin. Special values are bin 0 for underflow and bin nBin+1 for overflow. All other bins outside proper histogram range return 0.

vector< double > getBinContents ( ) const

Return bin contents.

Return bin contents and edges.

double getNEffective ( ) const

inline

Return effective entries (for weighted histograms = number of equivalent unweighted events for same statistical power).

double getXMean ( bool unbinned = true ) const

Compute mean value in X, by default unbinned.

Return <X> and error on <X>, unbinned from saved weight sums (default) or directly from the histogram bins (unbinned = false). In the latter case, the error estimate includes the difference between the binned and unbinned value summed in quadrature with the statistical error, as a measure of bin granularity error.

double getXMeanErr ( bool unbinned = true ) const

Error on mean value.

If no statistics, cannot compute error.

Get RMS and multiply by statistical power.

If binned, add estimated bin granularity error <x>_binned - <x>_unbinned.

double getXMedian ( bool includeOverUnder = false ) const

Return Median in X and its statistical error, ignoring underflow and overflow (default) or including them (includeOverUnder = true). By default, error includes granularity estimate obtained by comparing binned vs unbinned mean value, but this can be switched off (unbinned = false).

Compute median in X (with linear interpolation inside median bin). Note: absolute values of weights are used.

Include underflow and overflow bins in median definition?

If excess bins contain more than half, return low or high edge.

Should not arrive here. Safe return in any case.

double getXMedianErr ( bool includeOverUnder = true ) const

Compute statistical error on median in X ( + bin granularity estimate). Note: absolute values of weights are used.

If no statistics, cannot compute error.

Include underflow and overflow bins in median definition?

Laplace's formula for variance of median: 1/(4 nEff f(xmedian)^2).

Add uncertainty estimate from bin granularity from binned vs unbinned <x>.

double getXRMN	(	int	n = `2`,
		bool	unbinned = `true`
	)		const

Return RMS and equivalent n'th roots of n'th moments about the mean, and their error estimates. Up to n = 6, both unbinned and binned moments can be calculated. For n >= 7, and for all error estimates, only binned values are available. Note that (unlike ROOT), the error estimates do not assume normal distributions. RMN(2) = RMS is the standard root-mean-square deviation from the mean. RMN(3) is the cube root of the mean-cube deviation, cbrt(<(x - <x>)^3>). It is sensitive to single-sided tails, as are characteristic of many particle-physics distributions. RMN(4) adds sensitivity to double-sided long tails (eg BW vs Gaussian), and further sensitivity to long single-sided ones. Etc.

Get RMN = n'th root of n'th moment about the mean. Lowest ones: n = 2: RMS = sigma = width of (peaked) distribution. n = 3: cube root of third moment about the mean < ( x - <x> )^3 >. Sensitive to one-sided tails, as is characteristic of many particle-physics distributions. Related to skewness. n = 4: fourth root of fourth moment about the mean < ( x - <x> )^4 >. Sensitive to double-sided long tails (eg BW vs Gauss) and 4th-power asymptotics for single-sided ones. Related to kurtosis. ...

Compute from unbinned stored sums, or from binned histogram distributions.

1st central moment is always zero (Mean - Mean).

Unbinned RMN implemented for N = 2, 3, 4, 5, 6. One-pass algorithm, may suffer from loss of numerical accuracy if there are catastrophic cancellations among terms.

No further unbinned moments defined.

Binned: two-pass algorithm should be numerically more safe, but may be limited by bin granularity. First pass = compute binned mean. Note: absolute values of weights are used.

Second pass. Compute n'th moment about the mean (for any n).

General moments, for any n. Odd ones can be negative.

No further moments defined.

double getXRMNErr	(	int	n = `2`,
		bool	unbinned = `true`
	)		const

Error on n'th root of n'th moment about the mean. Computed using sigma2( <x^n> ) = < (x^n - <x>^n)^2 > / nEff Calculation always uses binned values, but if flag unbinned == false, a granularity uncertainty measure is added. Note: absolute values of weights are used.

Check if error can be computed.

First pass: compute binned mean.

Second pass: compute < (x^n - <x>^n)^2 >

Uncertainty on n'th root = 1/n * relative uncertainty.

If the moment itself was computed from binned distribution, add granularity uncertainty.

void normalize	(	double	f = `1`,
		bool	overflow = `true`
	)

Normalize sum of bin contents to value, with or without overflow bins.

Normalize bin contents to given sum, by default including overflow bins.

void normalizeIntegral	(	double	f = `1`,
		bool	overflow = `true`
	)

Normalize sum of bin areas to value, with or without overflow bins.

Normalize bin contents to given area, by default including overflow bins.

Hist & operator*= ( const Hist & h )

Multiply existing histogram by another one. (Assumes Gaussian uncertainty propagation.)

Result for sumxNw has to use binned values.

Hist & operator+= ( const Hist & h )

Operator overloading with member functions.

Add histogram to existing one.

Hist & operator+= ( double f )

Add constant offset to histogram. Squared weights treated as filling each bin with weight = f, For linear x, moments treated as filling with continuous f/dx. for logx, moments treated as filling with f at (log) centre of each bin.

Moments (for linX): analytical integral_xMin^xMax f/dx * x^m dx.

Moments (for logX): numerical sum of f * x^m.

Hist & operator-= ( double f )

Subtract constant offset from histogram. Squared weights treated as filling each bin with weight = -f. Moments treated as filling with continuous -f/dx.

Moments (for linX): analytical integral_xMin^xMax f/dx * x^m dx.

Moments (for logX): numerical sum of f * x^m.

Hist & operator/= ( const Hist & h )

Divide existing histogram by another one. (Assumes Gaussian uncertainty propagation.)

Result for sumxNw has to use binned values.

Hist & operator/= ( double f )

Divide histogram by constant.

Set empty contents when division by zero.

void pyplotTable	(	ostream &	os = `cout`,
		bool	isHist = `true`,
		bool	printError = `false`
	)		const

Print histogram contents as a table, as appropriate for Pyplot.

Set precision.

For plotting as a histogram one needs bin edges as last column.

And also an extra no-weights line to give final upper bin edge.

void rivetTable	(	ostream &	os = `cout`,
		bool	printError = `true`
	)		const

Print histogram contents as a table, in Rivet's *.dat style.

Print histogram vector bin by bin, with x range in first two columns and +- error in last two.

void table	(	ostream &	os = `cout`,
		bool	printOverUnder = `false`,
		bool	xMidBin = `true`,
		bool	printError = `false`
	)		const

Print histogram contents as a table (e.g. for Gnuplot).

Print histogram contents as a table (e.g. for Gnuplot, Rivet or Pyplot), optionally with statistical errors.

Print histogram vector bin by bin, with mean x as first column.

void takeFunc ( function< double(double)> func )

Take an arbitrary function of bin contents.

Result for sumxNw will use the new binned values.

void takeLog ( bool tenLog = true )

Take logarithm (base 10 or e) of bin contents.

Take 10-logarithm or natural logarithm of contents bin by bin.

Find smallest positive bin content, and put min a bit below.

Take base 10 or natural logarithm bin by bin, but ensure positivity.

void takeSqrt ( )

Take square root of bin contents.

Take square root of contents bin by bin; set 0 for negative content.

Friends And Related Function Documentation

Hist operator+	(	double	f,
		const Hist &	h1
	)

friend

Operator overloading with friends.

Implementation of operator overloading with friends.

ostream& operator<<	(	ostream &	os,
		const Hist &	h
	)

friend

Print a histogram with overloaded << operator.

Print a histogram: also operator overloading with friend.

Print a histogram with overloaded << operator.

Do not print empty histograms.

Write time and title.

Group bins, where required, to make printout have fewer columns. Avoid overflow.

Find minimum and maximum bin content.

Determine scale and step size for y axis.

Convert bin contents to integer form; fractional fill in top row.

Print histogram row by row.

Print sign and value of bin contents

Print sign and value of lower bin edge.

Print explanation if histogram cannot be shown.

Mean determines overall output format for moments.

Fixed or Scientific for ranges.

Fixed or Scientific for contents.

doStats and nEff determine if uncertainties should be printed.

Fixed or Scientific for nEffective.

First line.

Number of entries.

xMin.

Underflow

Mean.

RMS.

End of line.

Second line.

Sum of Weights (inside histogram range).

xMax.

Overflow

Median (excluding underflow and overflow bins).

nEff: Statistical power = effective number of unweighted entries. If nEff ~ h.inside, use same precision as for SumW.

Return to standard PYTHIA format.

void table	(	const Hist &	h1,
		const Hist &	h2,
		ostream &	os = `cout`,
		bool	printOverUnder = `false`,
		bool	xMidBin = `true`
	)

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Function Documentation

Friends And Related Function Documentation