#[1]Index [2]Search [3]Monte Carlo Integration [4]Histograms

   [5]GSL
   2.8
   ____________________
     * [6]Introduction
     * [7]Using the Library
     * [8]Error Handling
     * [9]Mathematical Functions
     * [10]Complex Numbers
     * [11]Polynomials
     * [12]Special Functions
     * [13]Vectors and Matrices
     * [14]Permutations
     * [15]Combinations
     * [16]Multisets
     * [17]Sorting
     * [18]BLAS Support
     * [19]Linear Algebra
     * [20]Eigensystems
     * [21]Fast Fourier Transforms (FFTs)
     * [22]Numerical Integration
     * [23]Random Number Generation
     * [24]Quasi-Random Sequences
     * [25]Random Number Distributions
     * [26]Statistics
     * [27]Running Statistics
     * [28]Moving Window Statistics
     * [29]Digital Filtering
     * [30]Histograms
     * [31]N-tuples
          + [32]The ntuple struct
          + [33]Creating ntuples
          + [34]Opening an existing ntuple file
          + [35]Writing ntuples
          + [36]Reading ntuples
          + [37]Closing an ntuple file
          + [38]Histogramming ntuple values
          + [39]Examples
          + [40]References and Further Reading
     * [41]Monte Carlo Integration
     * [42]Simulated Annealing
     * [43]Ordinary Differential Equations
     * [44]Interpolation
     * [45]Numerical Differentiation
     * [46]Chebyshev Approximations
     * [47]Series Acceleration
     * [48]Wavelet Transforms
     * [49]Discrete Hankel Transforms
     * [50]One Dimensional Root-Finding
     * [51]One Dimensional Minimization
     * [52]Multidimensional Root-Finding
     * [53]Multidimensional Minimization
     * [54]Linear Least-Squares Fitting
     * [55]Nonlinear Least-Squares Fitting
     * [56]Basis Splines
     * [57]Sparse Matrices
     * [58]Sparse BLAS Support
     * [59]Sparse Linear Algebra
     * [60]Physical Constants
     * [61]IEEE floating-point arithmetic
     * [62]Debugging Numerical Programs
     * [63]Contributors to GSL
     * [64]Autoconf Macros
     * [65]GSL CBLAS Library
     * [66]GNU General Public License
     * [67]GNU Free Documentation License

   [68]GSL
     * »
     * N-tuples
     * [69]View page source

   [70]Next [71]Previous
     ____________________________________________________________________________

N-tuples[72]¶

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

   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.

   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.

   All the ntuple functions are defined in the header file gsl_ntuple.h.

The ntuple struct[73]¶

   type gsl_ntuple[74]¶
          Ntuples are manipulated using the [75]gsl_ntuple 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:

typedef struct
  {
    FILE * file;
    void * ntuple_data;
    size_t size;
  } gsl_ntuple;

Creating ntuples[76]¶

   [77]gsl_ntuple *gsl_ntuple_create(char *filename, void *ntuple_data, size_t
          size)[78]¶
          This function creates a new write-only ntuple file [79]filename for
          ntuples of size [80]size 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
          [81]ntuple_data must be supplied--this is used to copy ntuples in and out
          of the file.

Opening an existing ntuple file[82]¶

   [83]gsl_ntuple *gsl_ntuple_open(char *filename, void *ntuple_data, size_t
          size)[84]¶
          This function opens an existing ntuple file [85]filename for reading and
          returns a pointer to a corresponding ntuple struct. The ntuples in the
          file must have size [86]size. A pointer to memory for the current ntuple
          row [87]ntuple_data must be supplied--this is used to copy ntuples in and
          out of the file.

Writing ntuples[88]¶

   int gsl_ntuple_write([89]gsl_ntuple *ntuple)[90]¶
          This function writes the current ntuple ntuple->ntuple_data of size
          ntuple->size to the corresponding file.

   int gsl_ntuple_bookdata([91]gsl_ntuple *ntuple)[92]¶
          This function is a synonym for [93]gsl_ntuple_write().

Reading ntuples[94]¶

   int gsl_ntuple_read([95]gsl_ntuple *ntuple)[96]¶
          This function reads the current row of the ntuple file for [97]ntuple and
          stores the values in ntuple->data.

Closing an ntuple file[98]¶

   int gsl_ntuple_close([99]gsl_ntuple *ntuple)[100]¶
          This function closes the ntuple file [101]ntuple and frees its associated
          allocated memory.

Histogramming ntuple values[102]¶

   Once an ntuple has been created its contents can be histogrammed in various ways
   using the function [103]gsl_ntuple_project(). 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.

   type gsl_ntuple_select_fn[104]¶
          The selection function determines which ntuple rows are selected for
          histogramming. It is defined by the following struct:

typedef struct
  {
    int (* function) (void * ntuple_data, void * params);
    void * params;
  } gsl_ntuple_select_fn;

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

   type gsl_ntuple_value_fn[105]¶
          The value function computes scalar values for those ntuple rows selected
          by the selection function:

typedef struct
  {
    double (* function) (void * ntuple_data, void * params);
    void * params;
  } gsl_ntuple_value_fn;

          In this case the struct component function should return the value to be
          added to the histogram for the ntuple row.

   int gsl_ntuple_project([106]gsl_histogram *h, [107]gsl_ntuple *ntuple,
          [108]gsl_ntuple_value_fn *value_func, [109]gsl_ntuple_select_fn
          *select_func)[110]¶
          This function updates the histogram [111]h from the ntuple [112]ntuple
          using the functions [113]value_func and [114]select_func. For each ntuple
          row where the selection function [115]select_func is non-zero the
          corresponding value of that row is computed using the function
          [116]value_func and added to the histogram. Those ntuple rows where
          [117]select_func 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.

Examples[118]¶

   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
   test.dat.
#include 
#include 
#include 

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", &ntuple_row,
                         sizeof (ntuple_row));

  gsl_rng_env_setup ();

  T = gsl_rng_default;
  r = gsl_rng_alloc (T);

  for (i = 0; i < 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);
  gsl_rng_free (r);

  return 0;
}

   The next program analyses the ntuple data in the file test.dat. 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.
#include 
#include 
#include 

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", &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 = &sel_func;
  S.params = &lower;

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

  gsl_ntuple_project (h, ntuple, &V, &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->x;
  y = data->y;
  z = data->z;

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

  return E2 > scale;
}

double
val_func (void *ntuple_data, void *params)
{
  (void)(params); /* avoid unused parameter warning */
  struct data * data = (struct data *) ntuple_data;
  double x, y, z;

  x = data->x;
  y = data->y;
  z = data->z;

  return x * x + y * y + z * z;
}

   [119]Fig. 15 shows the distribution of the selected events. Note the cut-off at
   the lower bound.
   [120]_images/ntuple.png

   Fig. 15 Distribution of selected events[121]¶

References and Further Reading[122]¶

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

   [123]Next [124]Previous
     ____________________________________________________________________________

   © Copyright 1996-2024 The GSL Team.
   Built with [125]Sphinx using a [126]theme provided by [127]Read the Docs.

References

   Visible links:
   1. http://www.gnu.org/software/gsl/doc/html/genindex.html
   2. http://www.gnu.org/software/gsl/doc/html/search.html
   3. http://www.gnu.org/software/gsl/doc/html/montecarlo.html
   4. http://www.gnu.org/software/gsl/doc/html/histogram.html
   5. http://www.gnu.org/software/gsl/doc/html/index.html
   6. http://www.gnu.org/software/gsl/doc/html/intro.html
   7. http://www.gnu.org/software/gsl/doc/html/usage.html
   8. http://www.gnu.org/software/gsl/doc/html/err.html
   9. http://www.gnu.org/software/gsl/doc/html/math.html
  10. http://www.gnu.org/software/gsl/doc/html/complex.html
  11. http://www.gnu.org/software/gsl/doc/html/poly.html
  12. http://www.gnu.org/software/gsl/doc/html/specfunc.html
  13. http://www.gnu.org/software/gsl/doc/html/vectors.html
  14. http://www.gnu.org/software/gsl/doc/html/permutation.html
  15. http://www.gnu.org/software/gsl/doc/html/combination.html
  16. http://www.gnu.org/software/gsl/doc/html/multiset.html
  17. http://www.gnu.org/software/gsl/doc/html/sort.html
  18. http://www.gnu.org/software/gsl/doc/html/blas.html
  19. http://www.gnu.org/software/gsl/doc/html/linalg.html
  20. http://www.gnu.org/software/gsl/doc/html/eigen.html
  21. http://www.gnu.org/software/gsl/doc/html/fft.html
  22. http://www.gnu.org/software/gsl/doc/html/integration.html
  23. http://www.gnu.org/software/gsl/doc/html/rng.html
  24. http://www.gnu.org/software/gsl/doc/html/qrng.html
  25. http://www.gnu.org/software/gsl/doc/html/randist.html
  26. http://www.gnu.org/software/gsl/doc/html/statistics.html
  27. http://www.gnu.org/software/gsl/doc/html/rstat.html
  28. http://www.gnu.org/software/gsl/doc/html/movstat.html
  29. http://www.gnu.org/software/gsl/doc/html/filter.html
  30. http://www.gnu.org/software/gsl/doc/html/histogram.html
  31. http://www.gnu.org/software/gsl/doc/html/ntuple.html
  32. http://www.gnu.org/software/gsl/doc/html/ntuple.html#the-ntuple-struct
  33. http://www.gnu.org/software/gsl/doc/html/ntuple.html#creating-ntuples
  34. http://www.gnu.org/software/gsl/doc/html/ntuple.html#opening-an-existing-ntuple-file
  35. http://www.gnu.org/software/gsl/doc/html/ntuple.html#writing-ntuples
  36. http://www.gnu.org/software/gsl/doc/html/ntuple.html#reading-ntuples
  37. http://www.gnu.org/software/gsl/doc/html/ntuple.html#closing-an-ntuple-file
  38. http://www.gnu.org/software/gsl/doc/html/ntuple.html#histogramming-ntuple-values
  39. http://www.gnu.org/software/gsl/doc/html/ntuple.html#examples
  40. http://www.gnu.org/software/gsl/doc/html/ntuple.html#references-and-further-reading
  41. http://www.gnu.org/software/gsl/doc/html/montecarlo.html
  42. http://www.gnu.org/software/gsl/doc/html/siman.html
  43. http://www.gnu.org/software/gsl/doc/html/ode-initval.html
  44. http://www.gnu.org/software/gsl/doc/html/interp.html
  45. http://www.gnu.org/software/gsl/doc/html/diff.html
  46. http://www.gnu.org/software/gsl/doc/html/cheb.html
  47. http://www.gnu.org/software/gsl/doc/html/sum.html
  48. http://www.gnu.org/software/gsl/doc/html/dwt.html
  49. http://www.gnu.org/software/gsl/doc/html/dht.html
  50. http://www.gnu.org/software/gsl/doc/html/roots.html
  51. http://www.gnu.org/software/gsl/doc/html/min.html
  52. http://www.gnu.org/software/gsl/doc/html/multiroots.html
  53. http://www.gnu.org/software/gsl/doc/html/multimin.html
  54. http://www.gnu.org/software/gsl/doc/html/lls.html
  55. http://www.gnu.org/software/gsl/doc/html/nls.html
  56. http://www.gnu.org/software/gsl/doc/html/bspline.html
  57. http://www.gnu.org/software/gsl/doc/html/spmatrix.html
  58. http://www.gnu.org/software/gsl/doc/html/spblas.html
  59. http://www.gnu.org/software/gsl/doc/html/splinalg.html
  60. http://www.gnu.org/software/gsl/doc/html/const.html
  61. http://www.gnu.org/software/gsl/doc/html/ieee754.html
  62. http://www.gnu.org/software/gsl/doc/html/debug.html
  63. http://www.gnu.org/software/gsl/doc/html/contrib.html
  64. http://www.gnu.org/software/gsl/doc/html/autoconf.html
  65. http://www.gnu.org/software/gsl/doc/html/cblas.html
  66. http://www.gnu.org/software/gsl/doc/html/gpl.html
  67. http://www.gnu.org/software/gsl/doc/html/fdl.html
  68. http://www.gnu.org/software/gsl/doc/html/index.html
  69. http://www.gnu.org/software/gsl/doc/html/_sources/ntuple.rst.txt
  70. http://www.gnu.org/software/gsl/doc/html/montecarlo.html
  71. http://www.gnu.org/software/gsl/doc/html/histogram.html
  72. http://www.gnu.org/software/gsl/doc/html/ntuple.html#n-tuples
  73. http://www.gnu.org/software/gsl/doc/html/ntuple.html#the-ntuple-struct
  74. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  75. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  76. http://www.gnu.org/software/gsl/doc/html/ntuple.html#creating-ntuples
  77. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  78. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_create
  79. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_create
  80. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_create
  81. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_create
  82. http://www.gnu.org/software/gsl/doc/html/ntuple.html#opening-an-existing-ntuple-file
  83. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  84. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_open
  85. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_open
  86. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_open
  87. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_open
  88. http://www.gnu.org/software/gsl/doc/html/ntuple.html#writing-ntuples
  89. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  90. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_write
  91. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  92. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_bookdata
  93. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_write
  94. http://www.gnu.org/software/gsl/doc/html/ntuple.html#reading-ntuples
  95. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
  96. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_read
  97. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_read
  98. http://www.gnu.org/software/gsl/doc/html/ntuple.html#closing-an-ntuple-file
  99. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
 100. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_close
 101. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_close
 102. http://www.gnu.org/software/gsl/doc/html/ntuple.html#histogramming-ntuple-values
 103. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 104. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_select_fn
 105. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_value_fn
 106. http://www.gnu.org/software/gsl/doc/html/histogram.html#c.gsl_histogram
 107. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple
 108. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_value_fn
 109. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_select_fn
 110. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 111. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 112. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 113. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 114. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 115. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 116. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 117. http://www.gnu.org/software/gsl/doc/html/ntuple.html#c.gsl_ntuple_project
 118. http://www.gnu.org/software/gsl/doc/html/ntuple.html#examples
 119. http://www.gnu.org/software/gsl/doc/html/ntuple.html#fig-ntuples
 120. http://www.gnu.org/software/gsl/doc/html/_images/ntuple.png
 121. http://www.gnu.org/software/gsl/doc/html/ntuple.html#id1
 122. http://www.gnu.org/software/gsl/doc/html/ntuple.html#references-and-further-reading
 123. http://www.gnu.org/software/gsl/doc/html/montecarlo.html
 124. http://www.gnu.org/software/gsl/doc/html/histogram.html
 125. https://www.sphinx-doc.org/
 126. https://github.com/readthedocs/sphinx_rtd_theme
 127. https://readthedocs.org/

   Hidden links:
 129. http://www.gnu.org/software/gsl/doc/html/index.html