File: gsl-ref_22.html

package info (click to toggle)
gsl-ref-html 1.6-1
links: PTS
area: main
in suites: sarge
size: 1,504 kB
ctags: 3,558
sloc: makefile: 36
file content (380 lines) | stat: -rw-r--r-- 10,382 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.54+ (gsl)
     from ../gsl-ref.texi -->

<TITLE>GNU Scientific Library -- Reference Manual - N-tuples</TITLE>
<!-- <LINK rel="stylesheet" title="Default Style Sheet" href="/css/texinfo.css" type="text/css"> -->
<link href="gsl-ref_23.html" rel=Next>
<link href="gsl-ref_21.html" rel=Previous>
<link href="gsl-ref_toc.html" rel=ToC>

</HEAD>
<BODY>
<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>.
<P><HR><P>


<H1><A NAME="SEC361" HREF="gsl-ref_toc.html#TOC361">N-tuples</A></H1>
<P>
<A NAME="IDX1825"></A>

</P>
<P>
This chapter describes functions for creating and manipulating
<I>ntuples</I>, sets of values associated with events.  The ntuples
are stored in files. Their values can be extracted in any combination
and <I>booked</I> in a histogram using a selection function.

</P>
<P>
The values to be stored are held in a user-defined data structure, and
an ntuple is created associating this data structure with a file.  The
values are then written to the file (normally inside a loop) using
the ntuple functions described below.

</P>
<P>
A histogram can be created from ntuple data by providing a selection
function and a value function.  The selection function specifies whether
an event should be included in the subset to be analyzed or not. The value
function computes the entry to be added to the histogram for each
event.

</P>
<P>
All the ntuple functions are defined in the header file
<TT>'gsl_ntuple.h'</TT>

</P>



<H2><A NAME="SEC362" HREF="gsl-ref_toc.html#TOC362">The ntuple struct</A></H2>

<P>
Ntuples are manipulated using the <CODE>gsl_ntuple</CODE> struct. This struct
contains information on the file where the ntuple data is stored, a
pointer to the current ntuple data row and the size of the user-defined
ntuple data struct.

</P>

<PRE class="example">
typedef struct {
    FILE * file;
    void * ntuple_data;
    size_t size;
} gsl_ntuple;
</PRE>



<H2><A NAME="SEC363" HREF="gsl-ref_toc.html#TOC363">Creating ntuples</A></H2>

<P>
<DL>
<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>
<DD><A NAME="IDX1826"></A>
This function creates a new write-only ntuple file <VAR>filename</VAR> for
ntuples of size <VAR>size</VAR> and returns a pointer to the newly created
ntuple struct.  Any existing file with the same name is truncated to
zero length and overwritten.  A pointer to memory for the current ntuple
row <VAR>ntuple_data</VAR> must be supplied--this is used to copy ntuples
in and out of the file.
</DL>

</P>


<H2><A NAME="SEC364" HREF="gsl-ref_toc.html#TOC364">Opening an existing ntuple file</A></H2>

<P>
<DL>
<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>
<DD><A NAME="IDX1827"></A>
This function opens an existing ntuple file <VAR>filename</VAR> for reading
and returns a pointer to a corresponding ntuple struct. The ntuples in
the file must have size <VAR>size</VAR>.  A pointer to memory for the current
ntuple row <VAR>ntuple_data</VAR> must be supplied--this is used to copy
ntuples in and out of the file.
</DL>

</P>


<H2><A NAME="SEC365" HREF="gsl-ref_toc.html#TOC365">Writing ntuples</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_ntuple_write</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
<DD><A NAME="IDX1828"></A>
This function writes the current ntuple <VAR>ntuple-&#62;ntuple_data</VAR> of
size <VAR>ntuple-&#62;size</VAR> to the corresponding file.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_ntuple_bookdata</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
<DD><A NAME="IDX1829"></A>
This function is a synonym for <CODE>gsl_ntuple_write</CODE>.
</DL>

</P>


<H2><A NAME="SEC366" HREF="gsl-ref_toc.html#TOC366">Reading ntuples</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_ntuple_read</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
<DD><A NAME="IDX1830"></A>
This function reads the current row of the ntuple file for <VAR>ntuple</VAR>
and stores the values in <VAR>ntuple-&#62;data</VAR>.
</DL>

</P>


<H2><A NAME="SEC367" HREF="gsl-ref_toc.html#TOC367">Closing an ntuple file</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_ntuple_close</B> <I>(gsl_ntuple * <VAR>ntuple</VAR>)</I>
<DD><A NAME="IDX1831"></A>
This function closes the ntuple file <VAR>ntuple</VAR> and frees its
associated allocated memory.
</DL>

</P>


<H2><A NAME="SEC368" HREF="gsl-ref_toc.html#TOC368">Histogramming ntuple values</A></H2>

<P>
Once an ntuple has been created its contents can be histogrammed in
various ways using the function <CODE>gsl_ntuple_project</CODE>.  Two
user-defined functions must be provided, a function to select events and
a function to compute scalar values. The selection function and the
value function both accept the ntuple row as a first argument and other
parameters as a second argument.

</P>
<P>
<A NAME="IDX1832"></A>
The <I>selection function</I> determines which ntuple rows are selected
for histogramming.  It is defined by the following struct,

<PRE class="smallexample">
typedef struct {
  int (* function) (void * ntuple_data, void * params);
  void * params;
} gsl_ntuple_select_fn;
</PRE>

<P>
The struct component <VAR>function</VAR> should return a non-zero value for
each ntuple row that is to be included in the histogram.

</P>
<P>
<A NAME="IDX1833"></A>
The <I>value function</I> computes scalar values for those ntuple rows
selected by the selection function,

<PRE class="smallexample">
typedef struct {
  double (* function) (void * ntuple_data, void * params);
  void * params;
} gsl_ntuple_value_fn;
</PRE>

<P>
In this case the struct component <VAR>function</VAR> should return the value
to be added to the histogram for the ntuple row.  

</P>
<P>
<A NAME="IDX1834"></A>
<A NAME="IDX1835"></A>
<DL>
<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>
<DD><A NAME="IDX1836"></A>
This function updates the histogram <VAR>h</VAR> from the ntuple <VAR>ntuple</VAR>
using the functions <VAR>value_func</VAR> and <VAR>select_func</VAR>. For each
ntuple row where the selection function <VAR>select_func</VAR> is non-zero the
corresponding value of that row is computed using the function
<VAR>value_func</VAR> and added to the histogram.  Those ntuple rows where
<VAR>select_func</VAR> returns zero are ignored.  New entries are added to
the histogram, so subsequent calls can be used to accumulate further
data in the same histogram.
</DL>

</P>


<H2><A NAME="SEC369" HREF="gsl-ref_toc.html#TOC369">Examples</A></H2>

<P>
The following example programs demonstrate the use of ntuples in
managing a large dataset.  The first program creates a set of 10,000
simulated "events", each with 3 associated values (x,y,z).  These
are generated from a gaussian distribution with unit variance, for
demonstration purposes, and written to the ntuple file <TT>'test.dat'</TT>.

</P>

<PRE class="example">
#include &#60;gsl/gsl_ntuple.h&#62;
#include &#60;gsl/gsl_rng.h&#62;
#include &#60;gsl/gsl_randist.h&#62;

struct data
{
  double x;
  double y;
  double z;
};

int
main (void)
{
  const gsl_rng_type * T;
  gsl_rng * r;

  struct data ntuple_row;
  int i;

  gsl_ntuple *ntuple 
    = gsl_ntuple_create ("test.dat", &#38;ntuple_row, 
                         sizeof (ntuple_row));

  gsl_rng_env_setup ();

  T = gsl_rng_default; 
  r = gsl_rng_alloc (T);

  for (i = 0; i &#60; 10000; i++)
    {
      ntuple_row.x = gsl_ran_ugaussian (r);
      ntuple_row.y = gsl_ran_ugaussian (r);
      ntuple_row.z = gsl_ran_ugaussian (r);
      
      gsl_ntuple_write (ntuple);
    }
  
  gsl_ntuple_close (ntuple);
  return 0;
}
</PRE>

<P>
The next program analyses the ntuple data in the file <TT>'test.dat'</TT>.
The analysis procedure is to compute the squared-magnitude of each
event, E^2=x^2+y^2+z^2, and select only those which exceed a
lower limit of 1.5.  The selected events are then histogrammed using
their E^2 values.

</P>

<PRE class="example">
#include &#60;math.h&#62;
#include &#60;gsl/gsl_ntuple.h&#62;
#include &#60;gsl/gsl_histogram.h&#62;

struct data
{
  double x;
  double y;
  double z;
};

int sel_func (void *ntuple_data, void *params);
double val_func (void *ntuple_data, void *params);

int
main (void)
{
  struct data ntuple_row;

  gsl_ntuple *ntuple 
    = gsl_ntuple_open ("test.dat", &#38;ntuple_row,
                       sizeof (ntuple_row));
  double lower = 1.5;

  gsl_ntuple_select_fn S;
  gsl_ntuple_value_fn V;

  gsl_histogram *h = gsl_histogram_alloc (100);
  gsl_histogram_set_ranges_uniform(h, 0.0, 10.0);

  S.function = &#38;sel_func;
  S.params = &#38;lower;

  V.function = &#38;val_func;
  V.params = 0;

  gsl_ntuple_project (h, ntuple, &#38;V, &#38;S);
  gsl_histogram_fprintf (stdout, h, "%f", "%f");
  gsl_histogram_free (h);
  gsl_ntuple_close (ntuple);

  return 0;
}

int
sel_func (void *ntuple_data, void *params)
{
  struct data * data = (struct data *) ntuple_data;  
  double x, y, z, E2, scale;
  scale = *(double *) params;
  
  x = data-&#62;x;
  y = data-&#62;y;
  z = data-&#62;z;

  E2 = x * x + y * y + z * z;

  return E2 &#62; scale;
}

double
val_func (void *ntuple_data, void *params)
{
  struct data * data = (struct data *) ntuple_data;  
  double x, y, z;

  x = data-&#62;x;
  y = data-&#62;y;
  z = data-&#62;z;

  return x * x + y * y + z * z;
}
</PRE>

<P>
The following plot shows the distribution of the selected events.
Note the cut-off at the lower bound.

</P>



<H2><A NAME="SEC370" HREF="gsl-ref_toc.html#TOC370">References and Further Reading</A></H2>
<P>
<A NAME="IDX1837"></A>
<A NAME="IDX1838"></A>

</P>
<P>
Further information on the use of ntuples can be found in the
documentation for the CERN packages PAW and HBOOK
(available online).

</P>

<P><HR><P>
<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>.
</BODY>
</HTML>