#
# = Histograms
# 1. {Histogram allocation}[link:hist_rdoc.html#label-Histogram+allocation]
# 1. {Copying histograms}[link:hist_rdoc.html#label-Copying+Histograms]
# 1. {Updating and accessing histogram elements}[link:hist_rdoc.html#label-Updating+and+accessing+histogram+elements]
# 1. {Searching histogram ranges}[link:hist_rdoc.html#label-Searching+histogram+ranges]
# 1. {Histogram Statistics}[link:hist_rdoc.html#label-Histogram+Statistics]
# 1. {Histogram Operations}[link:hist_rdoc.html#label-Histogram+Operations]
# 1. {Reading and writing histograms}[link:hist_rdoc.html#label-Reading+and+writing+histograms]
# 1. {Extensions}[link:hist_rdoc.html#label-Extentions]
#    1. {Histogram Operations}[link:hist_rdoc.html#label-Histogram+operations]
#    1. {Graph interface}[link:hist_rdoc.html#label-Graphics]
#    1. {Histogram Fittings}[link:hist_rdoc.html#label-Fitting]
# 1. {The histogram probability distribution}[link:hist_rdoc.html#label-The+histogram+probability+distribution]
#
# == Histogram allocation
# ---
# * GSL::Histogram.alloc(n)
# * GSL::Histogram.alloc(n, [xmin, xmax])
# * GSL::Histogram.alloc(n, xmin, xmax)
# * GSL::Histogram.alloc(n)
# * GSL::Histogram.alloc(array)
# * GSL::Histogram.alloc(vector)
#
#   Constructor for a histogram object with <tt>n</tt> bins.
#
#   Examples:
#
#   1. With an integer:
#        h = Histogram.alloc(4)  <--- Histogram of 4 bins.
#                                     The range is not defined yet.
#
#                  [ bin[0] )[ bin[1] )[ bin[2] )[ bin[3] )
#                  |---------|---------|---------|---------|
#               range[0]  range[1]  range[2]  range[3]  range[4]
#
#   1. With an array or a vector:
#        h = Histogram.alloc([1, 3, 7, 9, 20])  <--- Histogram of 4 bins.
#                                                  The range is initialized as
#                                                  range[0] = 1, range[1] = 3, ..., range[4] = 20.
#
#   1. With size and the range [min, max]:
#
#         >> h = Histogram.alloc(5, [0, 5])
#         >> h.range
#         => GSL::Histogram::Range:
#         [ 0.000e+00 1.000e+00 2.000e+00 3.000e+00 4.000e+00 5.000e+00 ]
#         >> h.bin
#         => GSL::Histogram::Bin:
#         [ 0.000e+00 0.000e+00 0.000e+00 0.000e+00 0.000e+00 ]
#         >> h.increment(2.5)
#         >> h.bin
#         => GSL::Histogram::Bin:
#         [ 0.000e+00 0.000e+00 1.000e+00 0.000e+00 0.000e+00 ]
#
# ---
# * GSL::Histogram.alloc_uniform(n, min, max)
# * GSL::Histogram.alloc_uniform(n, [min, max])
# * GSL::Histogram.equal_bins_p(h1, h2)
# * GSL::Histogram.equal_bins(h1, h2)
#
#   Return 1 if the all of the individual bin ranges of the two histograms
#   are identical, and 0 otherwise.
# ---
# * GSL::Histogram.equal_bins_p?(h1, h2)
# * GSL::Histogram.equal_bins?(h1, h2)
#
#   Return <tt>true</tt> if the all of the individual bin ranges of the two histograms
#   are identical, and <tt>false</tt> otherwise.
#
# ---
# * GSL::Histogram#set_ranges(v)
#
#   This sets the ranges of the existing histogram using a {GSL::Vector}[link:vector_rdoc.html] object.
# ---
# * GSL::Histogram#set_ranges_uniform(xmin, xmax)
# * GSL::Histogram#set_ranges_uniform([xmin, xmax])
#
#   This method sets the ranges of the existing histogram <tt>self</tt>
#   to cover the range <tt>xmin</tt> to <tt>xmax</tt> uniformly.
#   The values of the histogram bins are reset to zero.
#   The bin ranges are shown as below,
#      bin[0] corresponds to xmin <= x < xmin + d
#      bin[1] corresponds to xmin + d <= x < xmin + 2 d
#        ......
#      bin[n-1] corresponds to xmin + (n-1)d <= x < xmax
#   where d is the bin spacing, d = (xmax-xmin)/n.
#
# == Copying Histograms
# ---
# * GSL::Histogram.memcpy(dest, src)
#
#   Copies the histogram <tt>src</tt> into the pre-existing histogram <tt>dest</tt>,
#   making dest into an exact copy of <tt>src</tt>.
#   The two histograms must be of the same size.
# ---
# * GSL::Histogram#clone
#
#   Returns a newly created histogram which is an exact copy of the histogram
#   <tt>self</tt>.
#
# == Updating and accessing histogram elements
# ---
# * GSL::Histogram#increment(x, weight = 1)
# * GSL::Histogram#fill(x, weight = 1)
# * GSL::Histogram#accumulate(x, weight = 1)
#
#   These methods updates the histogram <tt>self</tt> by adding <tt>weight</tt>
#   (default = 1) to the bin whose range contains the coordinate <tt>x</tt>.
#   If <tt>x</tt> is an instance of <tt>GSL::Vector</tt> or <tt>Array</tt>,
#   all the elements are filled into the histogram.
#   If <tt>x</tt> is less than (greater than) the lower limit (upper limit)
#   of the histogram then none of bins are modified.
#
# ---
# * GSL::Histogram#increment2(x, weight = 1)
# * GSL::Histogram#fill2(x, weight = 1)
# * GSL::Histogram#accumulate2(x, weight = 1)
#
#   These methods updates the histogram <tt>self</tt> by adding <tt>weight</tt>
#   to the bin whose range contains the coordinate <tt>x</tt>.
#   If <tt>x</tt> is less than the lower limit, the lowest bin is incremented.
#   If <tt>x</tt> is greater than the upper limit, the highest bin is incremented.
#
# ---
# * GSL::Histogram#get(i)
# * \GSL::Histogram#[i]
#
#   These methods return the contents of the <tt>i</tt>-th bin of the histogram
#   <tt>self</tt>.
#
# ---
# * GSL::Hiatogram#get_range(i)
#
#   This method finds the upper and lower range limits of the <tt>i</tt>-th bin
#   of the histogram <tt>self</tt>, and returns an array [<tt>lower, upper</tt>].
#
# ---
# * GSL::Histogram#range
#
#   This returns a <tt>Vector::View</tt> object as a reference to the pointer
#   <tt>double *range</tt> in the <tt>gsl_histogram</tt> struct.
#
# ---
# * GSL::Histogram#bin
#
#   This returns a <tt>Vector::View</tt> object to access the pointer <tt>double *bin</tt> in the <tt>gsl_histogram</tt> struct.
#
# ---
# * GSL::Histogram#max
# * GSL::Histogram#min
# * GSL::Histogram#bins
#
#   These methods return the maximum upper and minimum lower range
#   limits and the number of bins of the histogram <tt>self</tt>.
#
# ---
# * GSL::Histogram#reset
#
#   This method resets all the bins in the histogram <tt>self</tt> to zero.
#
# == Searching histogram ranges
# ---
# * GSL::Histogram#find(x)
#
#   This method finds and sets the index i to the bin number which
#   covers the coordinate <tt>x</tt> in the histogram <tt>self</tt>.
#
# == Histogram Statistics
# ---
# * GSL::Histogram#max_val
#
#   This returns the maximum value contained in the histogram bins.
#
# ---
# * GSL::Histogram#max_bin
#
#   This returns the index of the bin containing the maximum value.
#   In the case where several bins contain the same maximum value the
#   smallest index is returned.
#
# ---
# * GSL::Histogram#min_val
#
#   This returns the minimum value contained in the histogram bins.
#
# ---
# * GSL::Histogram#min_bin
#
#   This returns the index of the bin containing the minimum value.
#   In the case where several bins contain the same maximum value
#   the smallest index is returned.
#
# ---
# * GSL::Histogram#mean
#
#   This returns the mean of the histogrammed variable,
#   where the histogram is regarded as a probability distribution.
#   Negative bin values are ignored for the purposes of this calculation.
#   The accuracy of the result is limited by the bin width.
#
# ---
# * GSL::Histogram#sigma
#
#   This function returns the standard deviation of the histogrammed variable,
#   where the histogram is regarded as a probability distribution.
#   Negative bin values are ignored for the purposes of this calculation.
#   The accuracy of the result is limited by the bin width.
#
# ---
# * GSL::Histogram#sum(istart = 0, iend = n-1)
#
#   The sum of values of the histogram <tt>self</tt> from the <tt>istart</tt>-th bin
#   to the <tt>iend</tt>-th bin.
#
#
# == Histogram Operations
#
# ---
# * GSL::Histogram#add(h2)
# * GSL::Histogram#sub(h2)
# * GSL::Histogram#mul(h2)
# * GSL::Histogram#div(h2)
# * GSL::Histogram#scale(val)
# * GSL::Histogram#shift(val)
#
#
#
# == Reading and writing histograms
# ---
# * GSL::Histogram#fwrite(io)
# * GSL::Histogram#fwrite(filename)
# * GSL::Histogram#fread(io)
# * GSL::Histogram#fread(filename)
# * GSL::Histogram#fprintf(io, range_format = "%e", bin_format = "%e")
# * GSL::Histogram#fprintf(filename, range_format = "%e", bin_format = "%e")
# * GSL::Histogram#fscanf(io)
# * GSL::Histogram#fscanf(filename)
#
#
# == Extentions
# === Histogram operations
# ---
# * GSL::Histogram#normalize
#
#   This methods scales the contents of the bins of histogram <tt>self</tt> by its
#   maximum value.
#
# ---
# * GSL::Histogram#rebin(m = 2)
#
#   This method creates a new histogram merging <tt>m</tt> bins in one in the
#   histogram <tt>self</tt>. This method cannot be used for histograms of
#   non-uniform bin size. If <tt>m</tt> is not an exact divider of the number
#   of bins of <tt>self</tt>, the range of the rebinned histogram is extended
#   not to lose the entries in the last <tt>m-1</tt> (at most) bins.
#
#   Example: a histogram <tt>h</tt> of size 5 with the range [0, 5), binned as
#
#       GSL::Histogram::Range:
#       [ 0.000e+00 1.000e+00 2.000e+00 3.000e+00 4.000e+00 5.000e+00 ]
#       GSL::Histogram::Bin:
#       [ 0.000e+00 3.000e+00 1.000e+00 1.000e+00 3.000e+00 ]
#
#   When a new histogram is created merging two bins into one as
#   <tt>h2 = h.rebin</tt>, then <tt>h2</tt> looks like
#
#       GSL::Histogram::Range:
#       [ 0.000e+00 2.000e+00 4.000e+00 6.000e+00 ]
#       GSL::Histogram::Bin:
#       [ 3.000e+00 2.000e+00 3.000e+00 ]
#
# ---
# * GSL::Histogram#reverse
#
#   This method create a new histogram reversing the order of the range and the bin of
#   histogram <tt>self</tt>.
#
# ---
# * GSL::Histogram#integrate(istart = 0, iend = n-1)
# * GSL::Histogram#integrate([istart, iend])
# * GSL::Histogram#integrate(direction = 1 or -1)
#
#   This method calculates cumulative counts of the histogram <tt>self</tt>
#   from the <tt>istart</tt>-th bin to the <tt>iend</tt>-th bin (<tt>iend</tt> inclusive),
#   and returns a <tt>GSL::Histogram::Integral</tt>
#   object. If <tt>istart <= iend</tt> (or <tt>direction == 1</tt>),
#   the <tt>i</tt>-th bin value of a
#   <tt>GSL::Histogram::Integral</tt> object <tt>hi</tt> created from a
#   <tt>GSL::Histogram</tt> <tt>h</tt> is given by <tt>hi[i] = hi[i-1] + h[i]</tt>.
#   If <tt>istart > iend</tt> (or <tt>direction == -1</tt>), <tt>hi[i] = hi[i+1] = h[i]</tt>.
#
# ---
# * GSL::Histogram::Integral#differentiate
# * GSL::Histogram::Integral#diff
#
# === Graphics
# ---
# * GSL::Histogram#graph(options)
#
#   This method uses the GNU plotutils <tt>graph</tt> to draw the histogram <tt>self</tt>.
#   The options as "-T X -C -l x" etc are given by a String.
#
# === Fitting
# ---
# * GSL::Histogram#fit_exponential(binstart = 0, binend = n-1)
#
#   This method fits the histogram <tt>self</tt> to an exponential model
#   <tt>h[n] = a exp(b x[n])</tt> using  the bins of indices from <tt>binstart</tt>
#   to <tt>binend</tt>. The result is returned as an Array of 6 elements,
#   <tt>[a, b, erra, errb, sumsq, dof]</tt>, where
#   * <tt>a</tt>: scale factor
#   * <tt>b</tt>: exponent
#   * <tt>erra, errb</tt>: fitting errors
#   * <tt>sumsq</tt>: fitting chi-squared (not reduced chi-squared)
#   * <tt>dof</tt>: degree-of-freedom, the number of bins used minus the number of parameters (2)
#
# ---
# * GSL::Histogram#fit_power(binstart = 0, binend = n-1)
#
#   This method fits the histogram <tt>self</tt> to a power-law model
#   <tt>h[n] = a x[n]^b</tt> using  the bins of indices from <tt>binstart</tt>
#   to <tt>binend</tt>. The result is returned as an Array of 6 elements,
#   <tt>[a, b, erra, errb, sumsq, dof]</tt>.
#
# ---
# * GSL::Histogram#fit_gaussian(binstart = 0, binend = n-1)
#
#   This method fits the histogram <tt>self</tt> to Gaussian distribution
#   using the bins of indices from <tt>binstart</tt> to <tt>binend</tt>,
#   and returns an Array of 8 elements,
#   <tt>[sigma, mean, height, errsig, errmean, errhei, sumsq, dof]</tt>.
#
#   Example:
#     #!/usr/bin/env ruby
#     require("gsl")
#
#     N = 10000
#     MAX = 8
#     rng = Rng.alloc
#
#     data = Ran.gaussian(rng, 1.5, N) + 2
#     h = Histogram.alloc(100, [-MAX, MAX])
#     h.increment(data)
#
#     sigma, mean, height, = h.fit_gaussian
#     x = Vector.linspace(-MAX, MAX, 100)
#     y = height*Ran::gaussian_pdf(x-mean, sigma)
#     GSL::graph(h, [x, y], "-T X -C -g 3")
#
# == The histogram probability distribution
# The probability distribution function for a histogram consists of a set of bins
# which measure the probability of an event falling into a given range of
# a continuous variable x. A probability distribution function is defined
# by the following class, which actually stores the cumulative probability
# distribution function. This is the natural quantity for generating samples
# via the inverse transform method, because there is a one-to-one mapping
# between the cumulative probability distribution and the range [0,1].
# It can be shown that by taking a uniform random number in this
# range and finding its corresponding coordinate in the cumulative probability
# distribution we obtain samples with the desired probability distribution.
#
# === Pdf class
# ---
# * GSL::Histogram::Pdf.alloc(n)
# * GSL::Histogram::Pdf.alloc(h)
#
#   Constructors. If a histogram <tt>h</tt> is given,
#   the probability distribution is initialized with the contents of <tt>h</tt>.
#
# ---
# * GSL::Histogram::Pdf#init(h)
#
#   This initializes the probability distribution <tt>self</tt> with the contents
#   of the histogram <tt>h</tt>.
#
# ---
# * GSL::Histogram::Pdf#sample(r)
#
#   This method uses <tt>r</tt>, a uniform random number between zero and one,
#   to compute a single random sample from the probability distribution <tt>self</tt>.
#   The algorithm used to compute the sample s is given by the following formula,
#      s = range[i] + delta * (range[i+1] - range[i])
#   where i is the index which satisfies
#   <tt>sum[i] <= r < sum[i+1]</tt> and <tt>delta</tt> is <tt>(r - sum[i])/(sum[i+1] - sum[i])</tt>.
#
# ---
# * GSL::Histogram::Pdf#n
#
#   This returns the number of bins of the probability distribution function.
#
# ---
# * GSL::Histogram:Pdf#range
#
#   This returns a <tt>Vector::View</tt> object as a reference to the pointer
#   <tt>double *range</tt> in the <tt>gsl_histogram_pdf</tt> struct.
# ---
# * GSL::Histogram:Pdf#sum
#
#   This returns a <tt>Vector::View</tt> object as a reference to the pointer
#   <tt>double *sum</tt> in the <tt>gsl_histogram_pdf</tt> struct.
#
# {prev}[link:stats_rdoc.html]
# {next}[link:hist2d_rdoc.html]
#
# {Reference index}[link:ref_rdoc.html]
# {top}[link:index.html]
#
#
