histogram.texi

开放gsl矩阵运算

determining these values without accessing the @code{gsl_histogram}
struct directly.
@end deftypefun

@deftypefun void gsl_histogram_reset (gsl_histogram * @var{h})
This function resets all the bins in the histogram @var{h} to zero.
@end deftypefun

@node Searching histogram ranges
@section Searching histogram ranges

The following functions are used by the access and update routines to
locate the bin which corresponds to a given @math{x} coordinate.

@deftypefun int gsl_histogram_find (const gsl_histogram * @var{h}, double @var{x}, size_t * @var{i})
This function finds and sets the index @var{i} to the bin number which
covers the coordinate @var{x} in the histogram @var{h}.  The bin is
located using a binary search. The search includes an optimization for
histograms with uniform range, and will return the correct bin
immediately in this case.  If @var{x} is found in the range of the
histogram then the function sets the index @var{i} and returns
@code{GSL_SUCCESS}.  If @var{x} lies outside the valid range of the
histogram then the function returns @code{GSL_EDOM} and the error
handler is invoked.
@end deftypefun

@node Histogram Statistics
@section Histogram Statistics

@deftypefun double gsl_histogram_max_val (const gsl_histogram * @var{h})
This function returns the maximum value contained in the histogram bins.
@end deftypefun

@deftypefun size_t gsl_histogram_max_bin (const gsl_histogram * @var{h})
This function 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.
@end deftypefun

@deftypefun double gsl_histogram_min_val (const gsl_histogram * @var{h})
This function returns the minimum value contained in the histogram bins.
@end deftypefun

@deftypefun size_t gsl_histogram_min_bin (const gsl_histogram * @var{h})
This function 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.
@end deftypefun

@deftypefun double gsl_histogram_mean (const gsl_histogram * @var{h})
This function 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.
@end deftypefun

@deftypefun double gsl_histogram_sigma (const gsl_histogram * @var{h})
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.
@end deftypefun

@node Histogram Operations
@section Histogram Operations

@deftypefun int gsl_histogram_equal_bins_p (const gsl_histogram *@var{h1}, const gsl_histogram *@var{h2})
This function returns 1 if the all of the individual bin
ranges of the two histograms are identical, and 0
otherwise.
@end deftypefun

@deftypefun int gsl_histogram_add (gsl_histogram *@var{h1}, const gsl_histogram *@var{h2})
This function adds the contents of the bins in histogram @var{h2} to the
corresponding bins of histogram @var{h1},  i.e. @math{h'_1(i) = h_1(i) +
h_2(i)}.  The two histograms must have identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram_sub (gsl_histogram *@var{h1}, const gsl_histogram *@var{h2})
This function subtracts the contents of the bins in histogram @var{h2}
from the corresponding bins of histogram @var{h1}, i.e. @math{h'_1(i) =
h_1(i) - h_2(i)}.  The two histograms must have identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram_mul (gsl_histogram *@var{h1}, const gsl_histogram *@var{h2})
This function multiplies the contents of the bins of histogram @var{h1}
by the contents of the corresponding bins in histogram @var{h2},
i.e. @math{h'_1(i) = h_1(i) * h_2(i)}.  The two histograms must have
identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram_div (gsl_histogram *@var{h1}, const gsl_histogram *@var{h2})
This function divides the contents of the bins of histogram @var{h1} by
the contents of the corresponding bins in histogram @var{h2},
i.e. @math{h'_1(i) = h_1(i) / h_2(i)}.  The two histograms must have
identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram_scale (gsl_histogram *@var{h}, double @var{scale})
This function multiplies the contents of the bins of histogram @var{h}
by the constant @var{scale}, i.e. @c{$h'_1(i) = h_1(i) * \hbox{\it scale}$}
@math{h'_1(i) = h_1(i) * scale}.
@end deftypefun

@deftypefun int gsl_histogram_shift (gsl_histogram *@var{h}, double @var{offset})
This function shifts the contents of the bins of histogram @var{h} by
the constant @var{offset}, i.e. @c{$h'_1(i) = h_1(i) + \hbox{\it offset}$}
@math{h'_1(i) = h_1(i) + offset}.
@end deftypefun

@node Reading and writing histograms
@section Reading and writing histograms

The library provides functions for reading and writing histograms to a file
as binary data or formatted text.

@deftypefun int gsl_histogram_fwrite (FILE * @var{stream}, const gsl_histogram * @var{h})
This function writes the ranges and bins of the histogram @var{h} to the
stream @var{stream} in binary format.  The return value is 0 for success
and @code{GSL_EFAILED} if there was a problem writing to the file.  Since
the data is written in the native binary format it may not be portable
between different architectures.
@end deftypefun

@deftypefun int gsl_histogram_fread (FILE * @var{stream}, gsl_histogram * @var{h})
This function reads into the histogram @var{h} from the open stream
@var{stream} in binary format.  The histogram @var{h} must be
preallocated with the correct size since the function uses the number of
bins in @var{h} to determine how many bytes to read.  The return value is
0 for success and @code{GSL_EFAILED} if there was a problem reading from
the file.  The data is assumed to have been written in the native binary
format on the same architecture.
@end deftypefun

@deftypefun int gsl_histogram_fprintf (FILE * @var{stream}, const gsl_histogram * @var{h}, const char * @var{range_format}, const char * @var{bin_format})
This function writes the ranges and bins of the histogram @var{h}
line-by-line to the stream @var{stream} using the format specifiers
@var{range_format} and @var{bin_format}.  These should be one of the
@code{%g}, @code{%e} or @code{%f} formats for floating point
numbers.  The function returns 0 for success and @code{GSL_EFAILED} if
there was a problem writing to the file.  The histogram output is
formatted in three columns, and the columns are separated by spaces,
like this,

@example
range[0] range[1] bin[0]
range[1] range[2] bin[1]
range[2] range[3] bin[2]
....
range[n-1] range[n] bin[n-1]
@end example

@noindent
The values of the ranges are formatted using @var{range_format} and the
value of the bins are formatted using @var{bin_format}.  Each line
contains the lower and upper limit of the range of the bins and the
value of the bin itself.  Since the upper limit of one bin is the lower
limit of the next there is duplication of these values between lines but
this allows the histogram to be manipulated with line-oriented tools.
@end deftypefun

@deftypefun int gsl_histogram_fscanf (FILE * @var{stream}, gsl_histogram * @var{h})
This function reads formatted data from the stream @var{stream} into the
histogram @var{h}.  The data is assumed to be in the three-column format
used by @code{gsl_histogram_fprintf}.  The histogram @var{h} must be
preallocated with the correct length since the function uses the size of
@var{h} to determine how many numbers to read.  The function returns 0
for success and @code{GSL_EFAILED} if there was a problem reading from
the file.
@end deftypefun

@node Resampling from histograms
@section Resampling from histograms
@cindex resampling from histograms
@cindex sampling from histograms
@cindex probability distributions, from histograms

A histogram made by counting events can be regarded as a measurement of
a probability distribution.  Allowing for statistical error, the height
of each bin represents the probability of an event where the value of
@math{x} falls in the range of that bin.  The probability distribution
function has the one-dimensional form @math{p(x)dx} where,

@tex
\beforedisplay
$$
p(x) = n_i/ (N w_i)
$$
\afterdisplay
@end tex
@ifinfo
@example
p(x) = n_i/ (N w_i)
@end example
@end ifinfo

@noindent
In this equation @math{n_i} is the number of events in the bin which
contains @math{x}, @math{w_i} is the width of the bin and @math{N} is
the total number of events.  The distribution of events within each bin
is assumed to be uniform.

@node The histogram probability distribution struct
@section The histogram probability distribution struct

The probability distribution function for a histogram consists of a set
of @dfn{bins} which measure the probability of an event falling into a
given range of a continuous variable @math{x}. A probability
distribution function is defined by the following struct, 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.

@deftp {Data Type} {gsl_histogram_pdf}
@table @code
@item size_t n
This is the number of bins used to approximate the probability
distribution function. 
@item double * range
The ranges of the bins are stored in an array of @var{n+1} elements
pointed to by @var{range}.
@item double * sum
The cumulative probability for the bins is stored in an array of
@var{n} elements pointed to by @var{sum}.
@end table
@end deftp
@comment 
@noindent
The following functions allow you to create a @code{gsl_histogram_pdf}
struct which represents this probability distribution and generate
random samples from it.

@deftypefun {gsl_histogram_pdf *} gsl_histogram_pdf_alloc (size_t n)
This function allocates memory for a probability distribution with
@var{n} bins and returns a pointer to a newly initialized
@code{gsl_histogram_pdf} struct. If insufficient memory is available a
null pointer is returned and the error handler is invoked with an error
code of @code{GSL_ENOMEM}.
@end deftypefun

@deftypefun int gsl_histogram_pdf_init (gsl_histogram_pdf * @var{p}, const gsl_histogram * @var{h})
This function initializes the probability distribution @var{p} with with
the contents of the histogram @var{h}. If any of the bins of @var{h} are
negative then the error handler is invoked with an error code of
@code{GSL_EDOM} because a probability distribution cannot contain
negative values.
@end deftypefun

@deftypefun void gsl_histogram_pdf_free (gsl_histogram_pdf * @var{p})
This function frees the probability distribution function @var{p} and
all of the memory associated with it.
@end deftypefun

@deftypefun double gsl_histogram_pdf_sample (const gsl_histogram_pdf * @var{p}, double @var{r})
This function uses @var{r}, a uniform random number between zero and
one, to compute a single random sample from the probability distribution
@var{p}.  The algorithm used to compute the sample @math{s} is given by
the following formula,

@tex
\beforedisplay
$$
s = \hbox{range}[i] + \delta * (\hbox{range}[i+1] - \hbox{range}[i])
$$
\afterdisplay
@end tex
@ifinfo
@example
s = range[i] + delta * (range[i+1] - range[i])
@end example
@end ifinfo

@noindent
where @math{i} is the index which satisfies 
@c{$sum[i] \le  r < sum[i+1]$}
@math{sum[i] <=  r < sum[i+1]} and 
@math{delta} is 
@c{$(r - sum[i])/(sum[i+1] - sum[i])$}
@math{(r - sum[i])/(sum[i+1] - sum[i])}.
@end deftypefun

@node Example programs for histograms
@section Example programs for histograms

The following program shows how to make a simple histogram of a column
of numerical data supplied on @code{stdin}.  The program takes three
arguments, specifying the upper and lower bounds of the histogram and
the number of bins.  It then reads numbers from @code{stdin}, one line at
a time, and adds them to the histogram.  When there is no more data to
read it prints out the accumulated histogram using
@code{gsl_histogram_fprintf}.

@example
#include <stdio.h>
#include <stdlib.h>
#include <gsl/gsl_histogram.h>

int
main (int argc, char **argv)
@{