PYTHIA  8.312
Public Member Functions | Static Public Member Functions | Friends | List of all members
Hist Class Reference

#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)
 
Histoperator= (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).
 
Histoperator+= (const Hist &h)
 Operator overloading with member functions. More...
 
Histoperator-= (const Hist &h)
 Subtract histogram from existing one.
 
Histoperator*= (const Hist &h)
 
Histoperator/= (const Hist &h)
 
Histoperator+= (double f)
 
Histoperator-= (double f)
 
Histoperator*= (double f)
 Multiply histogram by constant.
 
Histoperator/= (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 
)
friend

Print a table out of two histograms with same x axis (no errors printed).

Print a table out of two histograms with same x axis (e.g. for Gnuplot).

Require histogram x axes to agree.

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


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