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