#
# = 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.
#
# == The <tt>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.
#
# == 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.
#
# == 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]
#
#
