PYTHIA8/pythia8170/phpdoc/Histograms.php

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