PYTHIA8/pythia8170/xmldoc/Histograms.xml

   1 <chapter name="Histograms">
   2
   3 <h2>Histograms</h2>
   4
   5 The <code>Hist</code> class gives a simple implementation of
   6 one-dimensional histograms, useful for quick-and-dirty testing,
   7 without the need to link to more sophisticated packages.
   8 For this reson it is used in many of the
   9 <aloc href="SampleMainPrograms">sample main programs</aloc>
  10 found in the <code>examples</code> subdirectory.
  11
  12 <h3>Basic principles</h3>
  13
  14 We here provide a simple overview of what is involved.
  15 As a first step you need to declare a histogram, with name,
  16 title, number of bins and <ei>x</ei> range (from, to).
  17 <pre>
  18    Hist ZpT( "Z0 pT spectrum", 100, 0., 100.);
  19 </pre>
  20 Alternatively you can first declare it and later define it:
  21 <pre>
  22    Hist ZpT;
  23    ZpT.book( "Z0 pT spectrum", 100, 0., 100.);
  24 </pre>
  25
  26 Once declared, its contents can be added by repeated calls to
  27 <code>fill</code>,
  28 <pre>
  29    ZpT.fill( 22.7, 1.);
  30 </pre>
  31 where the first argument is the <ei>x</ei> value and the second the
  32 weight. Since the weight defaults to 1 the last argument could have
  33 been omitted in this case.
  34
  35 <p/>
  36 A set of overloaded operators have been defined, so that histograms
  37 can be added, subtracted, divided or multiplied by each other. Then the
  38 contents are modified accordingly bin by bin. Thus the relative
  39 deviation between two histograms <code>data</code> and
  40 <code>theory</code> can be found as
  41 <pre>
  42   diff = (data - theory) / (data + theory);
  43 </pre>
  44 assuming that <code>diff</code>, <code>data</code> and <code>theory</code>
  45 have been booked with the same number of bins and <ei>x</ei> range. That
  46 responsibility rests on the user; some checks are made for compatibility,
  47 but not enough to catch all possible mistakes.
  48
  49 <p/>
  50 Also overloaded operations with double real numbers are available.
  51 Again these four operations are defined bin by bin, i.e. the
  52 corresponding amount is added to, subtracted from, multiplied by or
  53 divided by each bin. The double number can come before or after the
  54 histograms, with obvious results. Thus the inverse of a histogram
  55 <code>result</code> is given by <code>1. / result</code>.
  56 The two kind of operations can be combined, e.g.
  57 <pre>
  58   allpT = ZpT + 2. * WpT
  59 </pre>
  60 Finally, also the <code>+=, -+, *=, /=</code> are overloaded, with
  61 the right-hand side being either a histogram or a real number.
  62
  63 <h3>Output format</h3>
  64
  65 <p/>
  66 A histogram can be printed by making use of the overloaded &lt;&lt;
  67 operator, e.g.:
  68 <pre>
  69    cout &lt;&lt; ZpT;
  70 </pre>
  71 The printout format is inspired by the old HBOOK one. To understand
  72 how to read this format, consider the simplified example
  73 <pre>
  74
  75         3.50*10^ 2  9
  76         3.00*10^ 2  X   7
  77         2.50*10^ 2  X  1X
  78         2.00*10^ 2  X6 XX
  79         1.50*10^ 2  XX5XX
  80         1.00*10^ 2  XXXXX
  81         0.50*10^ 2  XXXXX
  82
  83           Contents
  84             *10^ 2  31122
  85             *10^ 1  47208
  86             *10^ 0  79373
  87
  88           Low edge  --
  89             *10^ 1  10001
  90             *10^ 0  05050
  91 </pre>
  92 The key feature is that the <code>Contents</code> and
  93 <code>Low edge</code> have to be read vertically. For instance,
  94 the first bin has the contents
  95 <code>3 * 10^2 + 4 * 10^1 + 7 * 10^0 = 347</code>. Correspondingly,
  96 the other bins have contents 179, 123, 207 and 283. The first bin
  97 stretches from <code>-(1 * 10^1 + 0 * 10^0) = -10</code> to the
  98 beginning of the second bin, at <code>-(0 * 10^1 + 5 * 10^0) = -5</code>.
  99
 100 <p/>
 101 The visual representation above the contents give a simple impression
 102 of the shape. An <code>X</code> means that the contents are filled up
 103 to this level, a digit in the topmost row the fraction to which the
 104 last level is filled. So the 9 of the first column indicates this bin
 105 is filled 9/10 of the way from <code>3.00*10^2 = 300</code> to
 106 <code>3.50*10^2 = 350</code>, i.e. somewhere close to 345,
 107 or more precisely in the range 342.5 to 347.5.
 108
 109 <p/>
 110 The printout also provides some other information, such as the
 111 number of entries, i.e. how many times the histogram has been filled,
 112 the total weight inside the histogram, the total weight in underflow
 113 and overflow, and the mean value and root-mean-square width (disregarding
 114 underflow and overflow). The mean and width assumes that all the
 115 contents is in the middle of the respective bin. This is especially
 116 relevant when you plot a integer quantity, such as a multiplicity.
 117 Then it makes sense to book with limits that are half-integers, e.g.
 118 <pre>
 119    Hist multMPI( "number of multiparton interactions", 20, -0.5, 19.5);
 120 </pre>
 121 so that the bins are centered at 0, 1, 2, ..., respectively.  This also
 122 avoids ambiguities which bin gets to be filled if entries are
 123 exactly at the border between two bins. Also note that the
 124 <code>fill( xValue)</code> method automatically performs a cast
 125 to double precision where necessary, i.e. <code>xValue</code>
 126 can be an integer.
 127
 128 <h3>The methods</h3>
 129
 130 We here collect a more complete and formal overview of the methods.
 131
 132 <method name="Hist::Hist()">
 133 declare a histogram, but does not define it.
 134 </method>
 135
 136 <method name="Hist::Hist(string title, int numberOfBins, double xMin,
 137 double xMax)">
 138 declare and define a histogram, where
 139 <argument name="title">
 140 is a string with the title of the histogram at output,
 141 </argument>
 142 <argument name="numberOfBins">
 143 is the number of bin the <ei>x</ei> range will be subdivided into,
 144 limited to be at most 1000,
 145 </argument>
 146 <argument name="xMin">
 147 is the lower edge of the histogram,
 148 </argument>
 149 <argument name="xMax">
 150 is the upper edge of the histogram.
 151 </argument>
 152 </method>
 153
 154 <method name="Hist::Hist(const Hist& h)">
 155 creates an identical copy of the histogram in the argument,
 156 including bin contents.
 157 </method>
 158
 159 <method name="Hist::Hist(string title, const Hist& h)">
 160 creates an identical copy of the histogram in the argument,
 161 including bin contents, except that a new title is provided
 162 as first argument.
 163 </method>
 164
 165 <method name="Hist& Hist::operator=(const Hist& h)">
 166 copies all properties of the histogram in the argument,
 167 except that the original histogram title is retained.
 168 </method>
 169
 170 <method name="void Hist::book(string title, int numberOfBins,
 171 double xMin, double xMax)">
 172 define a histogram that previously was only declared;
 173 see above for the meaning of the arguments.
 174 </method>
 175
 176 <method name="void Hist::name(string title)">
 177 change the title of a histogram, but keep other properties unchanged.
 178 </method>
 179
 180 <method name="void Hist::null()">
 181 reset bin contents, but keep other histogram properties unchanged.
 182 </method>
 183
 184 <method name="void Hist::fill(double xValue, double weight)">
 185 fill the histogram, where
 186 <argument name="xValue">
 187 is the <ei>x</ei> position where the filling should occur, and
 188 </argument>
 189 <argument name="weight" default="1.">
 190 is the amount of weight to be added at this <ei>x</ei> value.
 191 </argument>
 192 </method>
 193
 194 <method name="friend ostream& operator<<(ostream& os, const Hist& h)">
 195 appends a simple histogram printout (see above for format) to the
 196 <code>ostream</code>, while leaving the histogram object itself
 197 unchanged. At most 100 columns are allowed to be displayed.
 198 If the number of bins is larger than 100 then the contents of
 199 adjacent bins are added to give the value in each column. (Two by two
 200 up to 200 bins, three by three up to 300, and so on, with the very
 201 last column possibly summing fewer rows than the others.)
 202 </method>
 203
 204 <method name="void Hist::table(ostream& os = cout)">
 205 </method>
 206 <methodmore name="void Hist::table(string fileName)">
 207 print a two-column table, where the first column gives the center of
 208 each bin and the second one the corresponding bin contents. The desired
 209 output stream or file name can be provided as argument. The former
 210 is more flexible (e.g., it allows easy append to an existing file),
 211 whereas the latter is simpler for the case that each histogram should
 212 be a file of its own. The table may be useful for plotting e.g. with
 213 Gnuplot.
 214 </methodmore>
 215
 216 <method name="friend void table(const Hist& h1, const Hist& h2,
 217 ostream& os = cout)">
 218 </method>
 219 <methodmore name="friend void table(const Hist& h1, const Hist& h2,
 220 string fileName)">
 221 print a three-column table, where the first column gives the center of
 222 each bin and the second and third ones the corresponding bin contents
 223 of the two histograms. Only works if the two histograms have the same
 224 x axis (within a tiny tolarance), else nothing will be done.
 225 </methodmore>
 226
 227 <method name="double Hist::getBinContent(int iBin)">
 228 return the value in bin <code>iBin</code>, ranging from 1 through
 229 <code>numberOfBins</code>, with <code>0</code> for underflow and
 230 <code>numberOfBins + 1</code> for overflow.
 231 </method>
 232
 233 <method name="int Hist::getEntries()">
 234 return the number of entries, i.e. the number of time that
 235 <code>fill(...)</code> has been called.
 236 </method>
 237
 238 <method name="bool Hist::sameSize(const Hist& h)">
 239 checks that the number of bins and upper and lower limits are the
 240 same as in the histogram in the argument.
 241 </method>
 242
 243 <method name="void Hist::takeLog(bool tenLog = true)">
 244 by default take 10-logarithm of current contents bin by bin. With
 245 optional argument <code>false</code> instead take <ei>e</ei>-logarithm
 246 of contents bin by bin. If to be used, then right before the
 247 histogram is output.
 248 </method>
 249
 250 <method name="void Hist::takeSqrt()">
 251 take square root of current contents bin by bin, with negative contents
 252 set to zero.
 253 </method>
 254
 255 <method name="Hist& Hist::operator+=(const Hist& h)">
 256 </method>
 257 <methodmore name="Hist& Hist::operator-=(const Hist& h)">
 258 adds or subtracts the current histogram by the contents of the
 259 histogram in the argument if <code>sameSize(...)</code> is true,
 260 else does nothing.
 261 </methodmore>
 262
 263 <method name="Hist& Hist::operator*=(const Hist& h)">
 264 </method>
 265 <methodmore name="Hist& Hist::operator/=(const Hist& h)">
 266 multiplies or divides the current histogram by the contents of the
 267 histogram in the argument if <code>sameSize(...)</code> is true,
 268 else does nothing.
 269 </methodmore>
 270
 271 <method name="Hist& Hist::operator+=(double f)">
 272 </method>
 273 <methodmore name="Hist& Hist::operator-=(double f)">
 274 adds or subtracts each bin content by the common offset <ei>f</ei>.
 275 </methodmore>
 276
 277 <method name="Hist& Hist::operator*=(double f)">
 278 </method>
 279 <methodmore name="Hist& Hist::operator*=(double f)">
 280 multiplies or divides each bin content by the common factor <ei>f</ei>.
 281 </methodmore>
 282
 283 <method name="friend Hist operator+(double f, const Hist& h1)">
 284 </method>
 285 <methodmore name="friend Hist operator+(const Hist& h1, double f)">
 286 </methodmore>
 287 <methodmore name="friend Hist operator+(const Hist& h1, const Hist h2)">
 288 add a constant to a histogram or two histograms to each other, bin by bin.
 289 </methodmore>
 290
 291 <method name="friend Hist operator-(double f, const Hist& h1)">
 292 </method>
 293 <methodmore name="friend Hist operator-(const Hist& h1, double f)">
 294 </methodmore>
 295 <methodmore name="friend Hist operator-(const Hist& h1, const Hist h2)">
 296 subtract a histogram from a constant, a constant from a histogram,
 297 or two histograms from each other, bin by bin.
 298 </methodmore>
 299
 300 <method name="friend Hist operator*(double f, const Hist& h1)">
 301 </method>
 302 <methodmore name="friend Hist operator*(const Hist& h1, double f)">
 303 </methodmore>
 304 <methodmore name="friend Hist operator*(const Hist& h1, const Hist h2)">
 305 multiply a constant by a histogram or two histograms by each other,
 306 bin by bin.
 307 </methodmore>
 308
 309 <method name="friend Hist operator/(double f, const Hist& h1)">
 310 </method>
 311 <methodmore name="friend Hist operator/(const Hist& h1, double f)">
 312 </methodmore>
 313 <methodmore name="friend Hist operator/(const Hist& h1, const Hist h2)">
 314 divide a constant by a histogram, a histogram by a constant,
 315 or two histograms by each other, bin by bin.
 316 </methodmore>
 317
 318 </chapter>
 319
 320 <!-- Copyright (C) 2012 Torbjorn Sjostrand -->