#
# = N-tuples
# 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 {GSL::Vector}[link:rdoc/vector_rdoc.html] or 
# a {GSL::Matrix}[link:rdoc/matrix_rdoc.html] object,
# and an ntuple is created associating this object 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.
#
# == {}[link:index.html"name="1] The <tt>GSL::Ntuple</tt> class
# ---
# * GSL::Ntuple.create(filename, v)
# * GSL::Ntuple.alloc(filename, v)
#
#   These create a new write-only ntuple file <tt>filename</tt> for ntuples. 
# Any existing file with the same name is truncated to zero length and overwritten. 
# A preexisting <tt>Vector</tt> object <tt>v</tt> for the current ntuple data must be supplied:
# this is used to copy ntuples in and out of the file.
#
# ---
# * GSL::Ntuple.open(filename, v)
#
#   This opens an existing ntuple file <tt>filename</tt> for reading. A preexisting
# <tt>Vector</tt> object <tt>v</tt> for the current ntuple data must be supplied.
#
# == {}[link:index.html"name="2] Writing and reading ntuples
# ---
# * GSL::Ntuple#write
# * GSL::Ntuple#bookdata
#
#   This method writes the current ntuple data to the corresponding file.
#
# ---
# * GSL::Ntuple#read
#
#   This method reads the current row of the ntuple file.
#
# == {}[link:index.html"name="3] Histogramming ntuple values
# Once an ntuple has been created its contents can be histogrammed in various ways using 
# the function 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.
#
# ---
# * GSL::Ntuple::SelectFn.alloc {block}
# * GSL::Ntuple::SelectFn.alloc(proc)
# * GSL::Ntuple::ValueFn.alloc {block}
# * GSL::Ntuple::ValueFn.alloc(proc)
#
#   Constructors for selection functions and value functions.
#   The selection function shoud return a non-zero value for each ntuple row that 
#   is to be included in the histogram. The value function should return the value to
#   be added to the histogram for the ntuple row.
#   
# ---
# * GSL::Ntuple::SelectFn#set_params(params)
# * GSL::Ntuple::ValueFn#set_params(params)
#
#   Set the parameters of the functions, by an array <tt>params</tt>.
#
# ---
# * GSL::Ntuple.project(h, n, valfn, selfn)
#
#   These methods updates the histogram <tt>h</tt> from the ntuple <tt>n</tt> using 
#   the functions <tt>valfn</tt> and <tt>selfn</tt>. For each ntuple row where the selection 
#   function <tt>selen</tt> is non-zero the corresponding value of that row is computed 
#   using the function value_func<tt>valfn</tt> and added to the histogram <tt>h</tt>. 
#   Those ntuple rows where <tt>selfn</tt> 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.
#
# {prev}[link:rdoc/hist2d_rdoc.html]
# {next}[link:rdoc/monte_rdoc.html]
#
# {Reference index}[link:rdoc/ref_rdoc.html]
# {top}[link:index.html]
#
#