histogram.texi

开放gsl矩阵运算

@cindex histograms
@cindex binning data
This chapter describes functions for creating histograms.  Histograms
provide a convenient way of summarizing the distribution of a set of
data. A histogram consists of a set of @dfn{bins} which count the number
of events falling into a given range of a continuous variable @math{x}.
In GSL the bins of a histogram contain floating-point numbers, so they
can be used to record both integer and non-integer distributions.  The
bins can use arbitrary sets of ranges (uniformly spaced bins are the
default).  Both one and two-dimensional histograms are supported.

Once a histogram has been created it can also be converted into a
probability distribution function.  The library provides efficient
routines for selecting random samples from probability
distributions.  This can be useful for generating simulations based real
data.

The functions are declared in the header files @file{gsl_histogram.h}
and @file{gsl_histogram2d.h}.

@menu
* The histogram struct::        
* Histogram allocation::        
* Copying Histograms::          
* Updating and accessing histogram elements::  
* Searching histogram ranges::  
* Histogram Statistics::        
* Histogram Operations::        
* Reading and writing histograms::  
* Resampling from histograms::  
* The histogram probability distribution struct::  
* Example programs for histograms::  
* Two dimensional histograms::  
* The 2D histogram struct::     
* 2D Histogram allocation::     
* Copying 2D Histograms::       
* Updating and accessing 2D histogram elements::  
* Searching 2D histogram ranges::  
* 2D Histogram Statistics::     
* 2D Histogram Operations::     
* Reading and writing 2D histograms::  
* Resampling from 2D histograms::  
* Example programs for 2D histograms::  
@end menu

@node The histogram struct
@section The histogram struct

A histogram is defined by the following struct,

@deftp {Data Type} {gsl_histogram}
@table @code
@item size_t n
This is the number of histogram bins
@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 * bin
The counts for each bin are stored in an array of @var{n} elements
pointed to by @var{bin}.  The bins are floating-point numbers, so you can
increment them by non-integer values if necessary.
@end table
@end deftp
@comment 
@noindent
The range for @var{bin}[i] is given by @var{range}[i] to
@var{range}[i+1].  For @math{n} bins there are @math{n+1} entries in the
array @var{range}.  Each bin is inclusive at the lower end and exclusive
at the upper end.  Mathematically this means that the bins are defined by
the following inequality,

@tex
\beforedisplay
$$
\hbox{bin[i] corresponds to range[i]} \le x < \hbox{range[i+1]}
$$
\afterdisplay
@end tex
@ifinfo
@display
bin[i] corresponds to range[i] <= x < range[i+1]
@end display
@end ifinfo

@noindent
Here is a diagram of the correspondence between ranges and bins on the
number-line for @math{x},

@smallexample

     [ bin[0] )[ bin[1] )[ bin[2] )[ bin[3] )[ bin[5] )
  ---|---------|---------|---------|---------|---------|---  x
   r[0]      r[1]      r[2]      r[3]      r[4]      r[5]

@end smallexample
@noindent
In this picture the values of the @var{range} array are denoted by
@math{r}.  On the left-hand side of each bin the square bracket
"@code{[}" denotes an inclusive lower bound 
(@c{$r \le x$}
@math{r <= x}), and the round parentheses "@code{)}" on the right-hand
side denote an exclusive upper bound (@math{x < r}).  Thus any samples
which fall on the upper end of the histogram are excluded.  If you want
to include this value for the last bin you will need to add an extra bin
to your histogram.

The @code{gsl_histogram} struct and its associated functions are defined
in the header file @file{gsl_histogram.h}.

@node Histogram allocation
@section Histogram allocation
The functions for allocating memory to a histogram follow the style of
@code{malloc} and @code{free}.  In addition they also perform their own
error checking.  If there is insufficient memory available to allocate a
histogram then the functions call the error handler (with an error
number of @code{GSL_ENOMEM}) in addition to returning a null pointer.
Thus if you use the library error handler to abort your program then it
isn't necessary to check every histogram @code{alloc}.

@deftypefun {gsl_histogram *} gsl_histogram_alloc (size_t @var{n})
This function allocates memory for a histogram with @var{n} bins, and
returns a pointer to a newly created @code{gsl_histogram} 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}. The
bins and ranges are not initialized, and should be prepared using one of
the range-setting functions below in order to make the histogram ready
for use.
@end deftypefun

@comment @deftypefun {gsl_histogram *} gsl_histogram_calloc (size_t @var{n})
@comment This function allocates memory for a histogram with @var{n} bins, and
@comment returns a pointer to its newly initialized @code{gsl_histogram} struct.
@comment The bins are uniformly spaced with a total range of 
@comment @c{$0 \le  x < n$}
@comment @math{0 <=  x < n},
@comment as shown in the table below.

@comment @tex
@comment \beforedisplay
@comment $$
@comment \matrix{
@comment \hbox{bin[0]}&\hbox{corresponds to}& 0 \le x < 1\cr
@comment \hbox{bin[1]}&\hbox{corresponds to}& 1 \le x < 2\cr
@comment \dots&\dots&\dots\cr
@comment \hbox{bin[n-1]}&\hbox{corresponds to}&n-1 \le x < n}
@comment $$
@comment \afterdisplay
@comment @end tex
@comment @ifinfo
@comment @display
@comment bin[0] corresponds to 0 <= x < 1
@comment bin[1] corresponds to 1 <= x < 2
@comment @dots{}
@comment bin[n-1] corresponds to n-1 <= x < n
@comment @end display
@comment @end ifinfo
@comment @noindent
@comment The bins are initialized to zero so the histogram is ready for use.

@comment If insufficient memory is available a null pointer is returned and the
@comment error handler is invoked with an error code of @code{GSL_ENOMEM}.
@comment @end deftypefun

@comment @deftypefun {gsl_histogram *} gsl_histogram_calloc_uniform (size_t @var{n}, double @var{xmin}, double @var{xmax})
@comment This function allocates memory for a histogram with @var{n} uniformly
@comment spaced bins from @var{xmin} to @var{xmax}, and returns a pointer to the
@comment newly initialized @code{gsl_histogram} struct. 
@comment If insufficient memory is available a null pointer is returned and the
@comment error handler is invoked with an error code of @code{GSL_ENOMEM}.
@comment @end deftypefun

@comment @deftypefun {gsl_histogram *} gsl_histogram_calloc_range (size_t @var{n}, double * @var{range})
@comment This function allocates a histogram of size @var{n} using the @math{n+1}
@comment bin ranges specified by the array @var{range}.
@comment @end deftypefun

@deftypefun int gsl_histogram_set_ranges (gsl_histogram * @var{h}, const double @var{range}[], size_t @var{size})
This function sets the ranges of the existing histogram @var{h} using
the array @var{range} of size @var{size}.  The values of the histogram
bins are reset to zero.  The @code{range} array should contain the
desired bin limits.  The ranges can be arbitrary, subject to the
restriction that they are monotonically increasing.

The following example shows how to create a histogram with logarithmic
bins with ranges [1,10), [10,100) and [100,1000).

@example
gsl_histogram * h = gsl_histogram_alloc (3);

/* bin[0] covers the range 1 <= x < 10 */
/* bin[1] covers the range 10 <= x < 100 */
/* bin[2] covers the range 100 <= x < 1000 */

double range[4] = @{ 1.0, 10.0, 100.0, 1000.0 @};

gsl_histogram_set_ranges (h, range, 4);
@end example
@noindent
Note that the size of the @var{range} array should be defined to be one
element bigger than the number of bins.  The additional element is
required for the upper value of the final bin.
@end deftypefun

@deftypefun int gsl_histogram_set_ranges_uniform (gsl_histogram * @var{h}, double @var{xmin}, double @var{xmax})
This function sets the ranges of the existing histogram @var{h} to cover
the range @var{xmin} to @var{xmax} uniformly.  The values of the
histogram bins are reset to zero.  The bin ranges are shown in the table
below,

@tex
\beforedisplay
$$
\matrix{\hbox{bin[0]}&\hbox{corresponds to}& xmin \le  x < xmin + d\cr
\hbox{bin[1]} &\hbox{corresponds to}& xmin + d \le  x < xmin + 2 d\cr
\dots&\dots&\dots\cr
\hbox{bin[n-1]} & \hbox{corresponds to}& xmin + (n-1)d \le  x < xmax}
$$
\afterdisplay
@end tex
@ifinfo
@display
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
@end display
@end ifinfo
@noindent
where @math{d} is the bin spacing, @math{d = (xmax-xmin)/n}.
@end deftypefun

@deftypefun void gsl_histogram_free (gsl_histogram * h)
This function frees the histogram @var{h} and all of the memory
associated with it.
@end deftypefun

@node Copying Histograms
@section Copying Histograms

@deftypefun int gsl_histogram_memcpy (gsl_histogram * @var{dest}, const gsl_histogram * @var{src})
This function copies the histogram @var{src} into the pre-existing
histogram @var{dest}, making @var{dest} into an exact copy of @var{src}.
The two histograms must be of the same size.
@end deftypefun

@deftypefun {gsl_histogram *} gsl_histogram_clone (const gsl_histogram * @var{src})
This function returns a pointer to a newly created histogram which is an
exact copy of the histogram @var{src}.
@end deftypefun

@node Updating and accessing histogram elements
@section Updating and accessing histogram elements

There are two ways to access histogram bins, either by specifying an
@math{x} coordinate or by using the bin-index directly.  The functions
for accessing the histogram through @math{x} coordinates use a binary
search to identify the bin which covers the appropriate range.

@deftypefun int gsl_histogram_increment (gsl_histogram * h, double x)
This function updates the histogram @var{h} by adding one (1.0) to the
bin whose range contains the coordinate @var{x}. 

If @var{x} lies in the valid range of the histogram then the function
returns zero to indicate success.  If @var{x} is less than the lower
limit of the histogram then the function returns @code{GSL_EDOM}, and
none of bins are modified.  Similarly, if the value of @var{x} is greater
than or equal to the upper limit of the histogram then the function
returns @code{GSL_EDOM}, and none of the bins are modified.  The error
handler is not called, however, since it is often necessary to compute
histogram for a small range of a larger dataset, ignoring the values
outside the range of interest.
@end deftypefun

@deftypefun int gsl_histogram_accumulate (gsl_histogram * @var{h}, double @var{x}, double @var{weight})
This function is similar to @code{gsl_histogram_increment} but increases
the value of the appropriate bin in the histogram @var{h} by the
floating-point number @var{weight}.
@end deftypefun

@deftypefun double gsl_histogram_get (const gsl_histogram * @var{h}, size_t @var{i})
This function returns the contents of the @var{i}th bin of the histogram
@var{h}.  If @var{i} lies outside the valid range of indices for the
histogram then the error handler is called with an error code of
@code{GSL_EDOM} and the function returns 0.
@end deftypefun

@deftypefun int gsl_histogram_get_range (const gsl_histogram * @var{h}, size_t @var{i}, double * @var{lower}, double * @var{upper})
This function finds the upper and lower range limits of the @var{i}th
bin of the histogram @var{h}.  If the index @var{i} is valid then the
corresponding range limits are stored in @var{lower} and @var{upper}.
The lower limit is inclusive (i.e. events with this coordinate are
included in the bin) and the upper limit is exclusive (i.e. events with
the coordinate of the upper limit are excluded and fall in the
neighboring higher bin, if it exists).  The function returns 0 to
indicate success.  If @var{i} lies outside the valid range of indices for
the histogram then the error handler is called and the function returns
an error code of @code{GSL_EDOM}.
@end deftypefun

@deftypefun double gsl_histogram_max (const gsl_histogram * @var{h})
@deftypefunx double gsl_histogram_min (const gsl_histogram * @var{h})
@deftypefunx size_t gsl_histogram_bins (const gsl_histogram * @var{h})
These functions return the maximum upper and minimum lower range limits
and the number of bins of the histogram @var{h}.  They provide a way of