3
<!-- This HTML file has been created by texi2html 1.54+ (gsl)
4
from ../gsl-ref.texi -->
6
<TITLE>GNU Scientific Library -- Reference Manual - N-tuples</TITLE>
7
<!-- <LINK rel="stylesheet" title="Default Style Sheet" href="/css/texinfo.css" type="text/css"> -->
8
<link href="gsl-ref_23.html" rel=Next>
9
<link href="gsl-ref_21.html" rel=Previous>
10
<link href="gsl-ref_toc.html" rel=ToC>
14
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_21.html">previous</A>, <A HREF="gsl-ref_23.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
18
<H1><A NAME="SEC361" HREF="gsl-ref_toc.html#TOC361">N-tuples</A></H1>
20
<A NAME="IDX1825"></A>
24
This chapter describes functions for creating and manipulating
25
<I>ntuples</I>, sets of values associated with events. The ntuples
26
are stored in files. Their values can be extracted in any combination
27
and <I>booked</I> in a histogram using a selection function.
31
The values to be stored are held in a user-defined data structure, and
32
an ntuple is created associating this data structure with a file. The
33
values are then written to the file (normally inside a loop) using
34
the ntuple functions described below.
38
A histogram can be created from ntuple data by providing a selection
39
function and a value function. The selection function specifies whether
40
an event should be included in the subset to be analyzed or not. The value
41
function computes the entry to be added to the histogram for each
46
All the ntuple functions are defined in the header file
47
<TT>'gsl_ntuple.h'</TT>
53
<H2><A NAME="SEC362" HREF="gsl-ref_toc.html#TOC362">The ntuple struct</A></H2>
56
Ntuples are manipulated using the <CODE>gsl_ntuple</CODE> struct. This struct
57
contains information on the file where the ntuple data is stored, a
58
pointer to the current ntuple data row and the size of the user-defined
73
<H2><A NAME="SEC363" HREF="gsl-ref_toc.html#TOC363">Creating ntuples</A></H2>
77
<DT><U>Function:</U> gsl_ntuple * <B>gsl_ntuple_create</B> <I>(char * <VAR>filename</VAR>, void * <VAR>ntuple_data</VAR>, size_t <VAR>size</VAR>)</I>
78
<DD><A NAME="IDX1826"></A>
79
This function creates a new write-only ntuple file <VAR>filename</VAR> for
80
ntuples of size <VAR>size</VAR> and returns a pointer to the newly created
81
ntuple struct. Any existing file with the same name is truncated to
82
zero length and overwritten. A pointer to memory for the current ntuple
83
row <VAR>ntuple_data</VAR> must be supplied--this is used to copy ntuples
84
in and out of the file.
90
<H2><A NAME="SEC364" HREF="gsl-ref_toc.html#TOC364">Opening an existing ntuple file</A></H2>
94
<DT><U>Function:</U> gsl_ntuple * <B>gsl_ntuple_open</B> <I>(char * <VAR>filename</VAR>, void * <VAR>ntuple_data</VAR>, size_t <VAR>size</VAR>)</I>
95
<DD><A NAME="IDX1827"></A>
96
This function opens an existing ntuple file <VAR>filename</VAR> for reading
97
and returns a pointer to a corresponding ntuple struct. The ntuples in
98
the file must have size <VAR>size</VAR>. A pointer to memory for the current
99
ntuple row <VAR>ntuple_data</VAR> must be supplied--this is used to copy
100
ntuples in and out of the file.
106
<H2><A NAME="SEC365" HREF="gsl-ref_toc.html#TOC365">Writing ntuples</A></H2>
110
<DT><U>Function:</U> int <B>gsl_ntuple_write</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
111
<DD><A NAME="IDX1828"></A>
112
This function writes the current ntuple <VAR>ntuple->ntuple_data</VAR> of
113
size <VAR>ntuple->size</VAR> to the corresponding file.
119
<DT><U>Function:</U> int <B>gsl_ntuple_bookdata</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
120
<DD><A NAME="IDX1829"></A>
121
This function is a synonym for <CODE>gsl_ntuple_write</CODE>.
127
<H2><A NAME="SEC366" HREF="gsl-ref_toc.html#TOC366">Reading ntuples</A></H2>
131
<DT><U>Function:</U> int <B>gsl_ntuple_read</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
132
<DD><A NAME="IDX1830"></A>
133
This function reads the current row of the ntuple file for <VAR>ntuple</VAR>
134
and stores the values in <VAR>ntuple->data</VAR>.
140
<H2><A NAME="SEC367" HREF="gsl-ref_toc.html#TOC367">Closing an ntuple file</A></H2>
144
<DT><U>Function:</U> int <B>gsl_ntuple_close</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
145
<DD><A NAME="IDX1831"></A>
146
This function closes the ntuple file <VAR>ntuple</VAR> and frees its
147
associated allocated memory.
153
<H2><A NAME="SEC368" HREF="gsl-ref_toc.html#TOC368">Histogramming ntuple values</A></H2>
156
Once an ntuple has been created its contents can be histogrammed in
157
various ways using the function <CODE>gsl_ntuple_project</CODE>. Two
158
user-defined functions must be provided, a function to select events and
159
a function to compute scalar values. The selection function and the
160
value function both accept the ntuple row as a first argument and other
161
parameters as a second argument.
165
<A NAME="IDX1832"></A>
166
The <I>selection function</I> determines which ntuple rows are selected
167
for histogramming. It is defined by the following struct,
169
<PRE class="smallexample">
171
int (* function) (void * ntuple_data, void * params);
173
} gsl_ntuple_select_fn;
177
The struct component <VAR>function</VAR> should return a non-zero value for
178
each ntuple row that is to be included in the histogram.
182
<A NAME="IDX1833"></A>
183
The <I>value function</I> computes scalar values for those ntuple rows
184
selected by the selection function,
186
<PRE class="smallexample">
188
double (* function) (void * ntuple_data, void * params);
190
} gsl_ntuple_value_fn;
194
In this case the struct component <VAR>function</VAR> should return the value
195
to be added to the histogram for the ntuple row.
199
<A NAME="IDX1834"></A>
200
<A NAME="IDX1835"></A>
202
<DT><U>Function:</U> int <B>gsl_ntuple_project</B> <I>(gsl_histogram * <VAR>h</VAR>, gsl_ntuple * <VAR>ntuple</VAR>, gsl_ntuple_value_fn *<VAR>value_func</VAR>, gsl_ntuple_select_fn *<VAR>select_func</VAR>)</I>
203
<DD><A NAME="IDX1836"></A>
204
This function updates the histogram <VAR>h</VAR> from the ntuple <VAR>ntuple</VAR>
205
using the functions <VAR>value_func</VAR> and <VAR>select_func</VAR>. For each
206
ntuple row where the selection function <VAR>select_func</VAR> is non-zero the
207
corresponding value of that row is computed using the function
208
<VAR>value_func</VAR> and added to the histogram. Those ntuple rows where
209
<VAR>select_func</VAR> returns zero are ignored. New entries are added to
210
the histogram, so subsequent calls can be used to accumulate further
211
data in the same histogram.
217
<H2><A NAME="SEC369" HREF="gsl-ref_toc.html#TOC369">Examples</A></H2>
220
The following example programs demonstrate the use of ntuples in
221
managing a large dataset. The first program creates a set of 10,000
222
simulated "events", each with 3 associated values (x,y,z). These
223
are generated from a gaussian distribution with unit variance, for
224
demonstration purposes, and written to the ntuple file <TT>'test.dat'</TT>.
228
<PRE class="example">
229
#include <gsl/gsl_ntuple.h>
230
#include <gsl/gsl_rng.h>
231
#include <gsl/gsl_randist.h>
243
const gsl_rng_type * T;
246
struct data ntuple_row;
250
= gsl_ntuple_create ("test.dat", &ntuple_row,
251
sizeof (ntuple_row));
253
gsl_rng_env_setup ();
256
r = gsl_rng_alloc (T);
258
for (i = 0; i < 10000; i++)
260
ntuple_row.x = gsl_ran_ugaussian (r);
261
ntuple_row.y = gsl_ran_ugaussian (r);
262
ntuple_row.z = gsl_ran_ugaussian (r);
264
gsl_ntuple_write (ntuple);
267
gsl_ntuple_close (ntuple);
273
The next program analyses the ntuple data in the file <TT>'test.dat'</TT>.
274
The analysis procedure is to compute the squared-magnitude of each
275
event, E^2=x^2+y^2+z^2, and select only those which exceed a
276
lower limit of 1.5. The selected events are then histogrammed using
281
<PRE class="example">
282
#include <math.h>
283
#include <gsl/gsl_ntuple.h>
284
#include <gsl/gsl_histogram.h>
293
int sel_func (void *ntuple_data, void *params);
294
double val_func (void *ntuple_data, void *params);
299
struct data ntuple_row;
302
= gsl_ntuple_open ("test.dat", &ntuple_row,
303
sizeof (ntuple_row));
306
gsl_ntuple_select_fn S;
307
gsl_ntuple_value_fn V;
309
gsl_histogram *h = gsl_histogram_alloc (100);
310
gsl_histogram_set_ranges_uniform(h, 0.0, 10.0);
312
S.function = &sel_func;
313
S.params = &lower;
315
V.function = &val_func;
318
gsl_ntuple_project (h, ntuple, &V, &S);
319
gsl_histogram_fprintf (stdout, h, "%f", "%f");
320
gsl_histogram_free (h);
321
gsl_ntuple_close (ntuple);
327
sel_func (void *ntuple_data, void *params)
329
struct data * data = (struct data *) ntuple_data;
330
double x, y, z, E2, scale;
331
scale = *(double *) params;
337
E2 = x * x + y * y + z * z;
339
return E2 > scale;
343
val_func (void *ntuple_data, void *params)
345
struct data * data = (struct data *) ntuple_data;
352
return x * x + y * y + z * z;
357
The following plot shows the distribution of the selected events.
358
Note the cut-off at the lower bound.
364
<H2><A NAME="SEC370" HREF="gsl-ref_toc.html#TOC370">References and Further Reading</A></H2>
366
<A NAME="IDX1837"></A>
367
<A NAME="IDX1838"></A>
371
Further information on the use of ntuples can be found in the
372
documentation for the CERN packages PAW and HBOOK
378
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_21.html">previous</A>, <A HREF="gsl-ref_23.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
added
removed
gsl-ref_22.html
