PYTHIA8/pythia8145/htmldoc/Histograms.html

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