htswanalysis/MACS/lib/gsl/gsl-1.11/doc/ntuple.texi

   1 @cindex ntuples
   2
   3 This chapter describes functions for creating and manipulating
   4 @dfn{ntuples}, sets of values associated with events.  The ntuples
   5 are stored in files. Their values can be extracted in any combination
   6 and @dfn{booked} in a histogram using a selection function.
   7
   8 The values to be stored are held in a user-defined data structure, and
   9 an ntuple is created associating this data structure with a file.  The
  10 values are then written to the file (normally inside a loop) using
  11 the ntuple functions described below.
  12
  13 A histogram can be created from ntuple data by providing a selection
  14 function and a value function.  The selection function specifies whether
  15 an event should be included in the subset to be analyzed or not. The value
  16 function computes the entry to be added to the histogram for each
  17 event.
  18
  19 All the ntuple functions are defined in the header file
  20 @file{gsl_ntuple.h}
  21
  22 @menu
  23 * The ntuple struct::
  24 * Creating ntuples::
  25 * Opening an existing ntuple file::
  26 * Writing ntuples::
  27 * Reading ntuples ::
  28 * Closing an ntuple file::
  29 * Histogramming ntuple values::
  30 * Example ntuple programs::
  31 * Ntuple References and Further Reading::
  32 @end menu
  33
  34 @node The ntuple struct
  35 @section The ntuple struct
  36
  37 Ntuples are manipulated using the @code{gsl_ntuple} struct. This struct
  38 contains information on the file where the ntuple data is stored, a
  39 pointer to the current ntuple data row and the size of the user-defined
  40 ntuple data struct.
  41
  42 @example
  43 typedef struct @{
  44     FILE * file;
  45     void * ntuple_data;
  46     size_t size;
  47 @} gsl_ntuple;
  48 @end example
  49
  50 @node Creating ntuples
  51 @section Creating ntuples
  52
  53 @deftypefun {gsl_ntuple *} gsl_ntuple_create (char * @var{filename}, void * @var{ntuple_data}, size_t @var{size})
  54 This function creates a new write-only ntuple file @var{filename} for
  55 ntuples of size @var{size} and returns a pointer to the newly created
  56 ntuple struct.  Any existing file with the same name is truncated to
  57 zero length and overwritten.  A pointer to memory for the current ntuple
  58 row @var{ntuple_data} must be supplied---this is used to copy ntuples
  59 in and out of the file.
  60 @end deftypefun
  61
  62 @node Opening an existing ntuple file
  63 @section Opening an existing ntuple file
  64
  65 @deftypefun {gsl_ntuple *} gsl_ntuple_open (char * @var{filename}, void * @var{ntuple_data}, size_t @var{size})
  66 This function opens an existing ntuple file @var{filename} for reading
  67 and returns a pointer to a corresponding ntuple struct. The ntuples in
  68 the file must have size @var{size}.  A pointer to memory for the current
  69 ntuple row @var{ntuple_data} must be supplied---this is used to copy
  70 ntuples in and out of the file.
  71 @end deftypefun
  72
  73 @node Writing ntuples
  74 @section Writing ntuples
  75
  76 @deftypefun int gsl_ntuple_write (gsl_ntuple * @var{ntuple})
  77 This function writes the current ntuple @var{ntuple->ntuple_data} of
  78 size @var{ntuple->size} to the corresponding file.
  79 @end deftypefun
  80
  81 @deftypefun int gsl_ntuple_bookdata (gsl_ntuple * @var{ntuple})
  82 This function is a synonym for @code{gsl_ntuple_write}.
  83 @end deftypefun
  84
  85 @node Reading ntuples
  86 @section Reading ntuples
  87
  88 @deftypefun int gsl_ntuple_read (gsl_ntuple * @var{ntuple})
  89 This function reads the current row of the ntuple file for @var{ntuple}
  90 and stores the values in @var{ntuple->data}.
  91 @end deftypefun
  92
  93 @node Closing an ntuple file
  94 @section Closing an ntuple file
  95
  96 @deftypefun int gsl_ntuple_close (gsl_ntuple * @var{ntuple})
  97 This function closes the ntuple file @var{ntuple} and frees its
  98 associated allocated memory.
  99 @end deftypefun
 100
 101 @node Histogramming ntuple values
 102 @section Histogramming ntuple values
 103
 104 Once an ntuple has been created its contents can be histogrammed in
 105 various ways using the function @code{gsl_ntuple_project}.  Two
 106 user-defined functions must be provided, a function to select events and
 107 a function to compute scalar values. The selection function and the
 108 value function both accept the ntuple row as a first argument and other
 109 parameters as a second argument.
 110
 111 @cindex selection function, ntuples
 112 The @dfn{selection function} determines which ntuple rows are selected
 113 for histogramming.  It is defined by the following struct,
 114 @smallexample
 115 typedef struct @{
 116   int (* function) (void * ntuple_data, void * params);
 117   void * params;
 118 @} gsl_ntuple_select_fn;
 119 @end smallexample
 120
 121 @noindent
 122 The struct component @var{function} should return a non-zero value for
 123 each ntuple row that is to be included in the histogram.
 124
 125 @cindex value function, ntuples
 126 The @dfn{value function} computes scalar values for those ntuple rows
 127 selected by the selection function,
 128 @smallexample
 129 typedef struct @{
 130   double (* function) (void * ntuple_data, void * params);
 131   void * params;
 132 @} gsl_ntuple_value_fn;
 133 @end smallexample
 134
 135 @noindent
 136 In this case the struct component @var{function} should return the value
 137 to be added to the histogram for the ntuple row.
 138
 139 @cindex histogram, from ntuple
 140 @cindex projection of ntuples
 141 @deftypefun int gsl_ntuple_project (gsl_histogram * @var{h}, gsl_ntuple * @var{ntuple}, gsl_ntuple_value_fn * @var{value_func}, gsl_ntuple_select_fn * @var{select_func})
 142 This function updates the histogram @var{h} from the ntuple @var{ntuple}
 143 using the functions @var{value_func} and @var{select_func}. For each
 144 ntuple row where the selection function @var{select_func} is non-zero the
 145 corresponding value of that row is computed using the function
 146 @var{value_func} and added to the histogram.  Those ntuple rows where
 147 @var{select_func} returns zero are ignored.  New entries are added to
 148 the histogram, so subsequent calls can be used to accumulate further
 149 data in the same histogram.
 150 @end deftypefun
 151
 152 @node Example ntuple programs
 153 @section Examples
 154
 155 The following example programs demonstrate the use of ntuples in
 156 managing a large dataset.  The first program creates a set of 10,000
 157 simulated ``events'', each with 3 associated values @math{(x,y,z)}.  These
 158 are generated from a gaussian distribution with unit variance, for
 159 demonstration purposes, and written to the ntuple file @file{test.dat}.
 160
 161 @example
 162 @verbatiminclude examples/ntuplew.c
 163 @end example
 164
 165 @noindent
 166 The next program analyses the ntuple data in the file @file{test.dat}.
 167 The analysis procedure is to compute the squared-magnitude of each
 168 event, @math{E^2=x^2+y^2+z^2}, and select only those which exceed a
 169 lower limit of 1.5.  The selected events are then histogrammed using
 170 their @math{E^2} values.
 171
 172 @example
 173 @verbatiminclude examples/ntupler.c
 174 @end example
 175
 176 @need 3000
 177 The following plot shows the distribution of the selected events.
 178 Note the cut-off at the lower bound.
 179
 180 @iftex
 181 @sp 1
 182 @center @image{ntuple,3.4in}
 183 @end iftex
 184
 185 @node Ntuple References and Further Reading
 186 @section References and Further Reading
 187 @cindex PAW
 188 @cindex HBOOK
 189
 190 Further information on the use of ntuples can be found in the
 191 documentation for the @sc{cern} packages @sc{paw} and @sc{hbook}
 192 (available online).
 193
 194