histogram.texi

开放gsl矩阵运算

  double a, b;
  size_t n;

  if (argc != 4)
    @{
      printf ("Usage: gsl-histogram xmin xmax n\n"
              "Computes a histogram of the data "
              "on stdin using n bins from xmin "
              "to xmax\n");
      exit (0);
    @}

  a = atof (argv[1]);
  b = atof (argv[2]);
  n = atoi (argv[3]);

  @{
    int status;
    double x;

    gsl_histogram * h = gsl_histogram_alloc (n);
            
    gsl_histogram_set_uniform (h, a, b);

    while (fscanf(stdin, "%lg", &x) == 1)
      @{
        gsl_histogram_increment(h, x);
      @}

    gsl_histogram_fprintf (stdout, h, "%g", "%g");

    gsl_histogram_free (h);
  @}
  
  exit (0);
@}
@end example

@noindent
Here is an example of the program in use.  We generate 10000 random
samples from a Cauchy distribution with a width of 30 and histogram
them over the range -100 to 100, using 200 bins.

@example
$ gsl-randist 0 10000 cauchy 30 
   | gsl-histogram -100 100 200 > histogram.dat
@end example

@noindent
A plot of the resulting histogram shows the familiar shape of the
Cauchy distribution and the fluctuations caused by the finite sample
size.

@example
$ awk '@{print $1, $3 ; print $2, $3@}' histogram.dat 
   | graph -T X
@end example

@iftex
@sp 1
@center @image{histogram,4in}
@end iftex

@node Two dimensional histograms
@section Two dimensional histograms
@cindex two dimensional histograms
@cindex 2D histograms

A two dimensional histogram consists of a set of @dfn{bins} which count
the number of events falling in a given area of the @math{(x,y)}
plane.  The simplest way to use a two dimensional histogram is to record
two-dimensional position information, @math{n(x,y)}.  Another possibility
is to form a @dfn{joint distribution} by recording related
variables.  For example a detector might record both the position of an
event (@math{x}) and the amount of energy it deposited @math{E}.  These
could be histogrammed as the joint distribution @math{n(x,E)}.

@node The 2D histogram struct
@section The 2D histogram struct

Two dimensional histograms are defined by the following struct,

@deftp {Data Type} {gsl_histogram2d}
@table @code
@item size_t nx, ny
This is the number of histogram bins in the x and y directions.
@item double * xrange
The ranges of the bins in the x-direction are stored in an array of
@var{nx + 1} elements pointed to by @var{xrange}.
@item double * yrange
The ranges of the bins in the y-direction are stored in an array of
@var{ny + 1} pointed to by @var{yrange}.
@item double * bin
The counts for each bin are stored in an array pointed to by @var{bin}.
The bins are floating-point numbers, so you can increment them by
non-integer values if necessary.  The array @var{bin} stores the two
dimensional array of bins in a single block of memory according to the
mapping @code{bin(i,j)} = @code{bin[i * ny + j]}.
@end table
@end deftp
@comment 
@noindent
The range for @code{bin(i,j)} is given by @code{xrange[i]} to
@code{xrange[i+1]} in the x-direction and @code{yrange[j]} to
@code{yrange[j+1]} in the y-direction.  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
$$
\matrix{
\hbox{bin(i,j) corresponds to} & 
          \hbox{\it xrange}[i] \le x < \hbox{\it xrange}[i+1] \cr
   \hbox{and} & \hbox{\it yrange}[j] \le y < \hbox{\it yrange}[j+1]}
$$
\afterdisplay
@end tex
@ifinfo
@display
bin(i,j) corresponds to xrange[i] <= x < xrange[i+1]
                    and yrange[j] <= y < yrange[j+1]
@end display
@end ifinfo
@noindent
Note that any samples which fall on the upper sides of the histogram are
excluded.  If you want to include these values for the side bins you will
need to add an extra row or column to your histogram.

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

@node 2D Histogram allocation
@section 2D Histogram allocation

The functions for allocating memory to a 2D 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 2D histogram @code{alloc}.

@deftypefun {gsl_histogram2d *} gsl_histogram2d_alloc (size_t @var{nx}, size_t @var{ny})
This function allocates memory for a two-dimensional histogram with
@var{nx} bins in the x direction and @var{ny} bins in the y direction.
The function returns a pointer to a newly created @code{gsl_histogram2d}
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 must be initialized with one of
the functions below before the histogram is ready for use.
@end deftypefun

@comment @deftypefun {gsl_histogram2d *} gsl_histogram2d_calloc (size_t @var{nx}, size_t @var{ny})
@comment This function allocates memory for a two-dimensional histogram with
@comment @var{nx} bins in the x direction and @var{ny} bins in the y
@comment direction.  The function returns a pointer to a newly initialized
@comment @code{gsl_histogram2d} struct.  The bins are uniformly spaced with a
@comment total range of 
@comment @c{$0 \le  x < nx$}
@comment @math{0 <= x < nx} in the x-direction and 
@comment @c{$0 \le  y < ny$} 
@comment @math{0 <=  y < ny} in the y-direction, as shown in the table below.
@comment 
@comment The bins are initialized to zero so the histogram is ready for use.
@comment 
@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 
@comment @deftypefun {gsl_histogram2d *} gsl_histogram2d_calloc_uniform (size_t @var{nx}, size_t @var{ny}, double @var{xmin}, double @var{xmax}, double @var{ymin}, double @var{ymax})
@comment This function allocates a histogram of size @var{nx}-by-@var{ny} which
@comment uniformly covers the ranges @var{xmin} to @var{xmax} and @var{ymin} to
@comment @var{ymax} in the @math{x} and @math{y} directions respectively.
@comment @end deftypefun
@comment 
@comment @deftypefun {gsl_histogram2d *} gsl_histogram2d_calloc_range (size_t @var{nx}, size_t @var{ny}, double * @var{xrange}, double * @var{yrange})
@comment This function allocates a histogram of size @var{nx}-by-@var{ny} using
@comment the @math{nx+1} and @math{ny+1} bin ranges specified by the arrays
@comment @var{xrange} and @var{xyrange}.
@comment @end deftypefun

@deftypefun int gsl_histogram2d_set_ranges (gsl_histogram2d * @var{h},  const double @var{xrange}[], size_t @var{xsize}, const double @var{yrange}[], size_t @var{ysize})
This function sets the ranges of the existing histogram @var{h} using
the arrays @var{xrange} and @var{yrange} of size @var{xsize} and
@var{ysize} respectively.  The values of the histogram bins are reset to
zero.
@end deftypefun

@deftypefun int gsl_histogram2d_set_ranges_uniform (gsl_histogram2d * @var{h}, double @var{xmin}, double @var{xmax}, double @var{ymin}, double @var{ymax})
This function sets the ranges of the existing histogram @var{h} to cover
the ranges @var{xmin} to @var{xmax} and @var{ymin} to @var{ymax}
uniformly.  The values of the histogram bins are reset to zero.
@end deftypefun

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

@node Copying 2D Histograms
@section Copying 2D Histograms

@deftypefun int gsl_histogram2d_memcpy (gsl_histogram2d * @var{dest}, const gsl_histogram2d * @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_histogram2d *} gsl_histogram2d_clone (const gsl_histogram2d * @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 2D histogram elements
@section Updating and accessing 2D histogram elements

You can access the bins of a two-dimensional histogram either by
specifying a pair of @math{(x,y)} coordinates or by using the bin
indices @math{(i,j)} directly.  The functions for accessing the histogram
through @math{(x,y)} coordinates use binary searches in the x and y
directions to identify the bin which covers the appropriate range.

@deftypefun int gsl_histogram2d_increment (gsl_histogram2d * @var{h}, double @var{x}, double @var{y})
This function updates the histogram @var{h} by adding one (1.0) to the
bin whose x and y ranges contain the coordinates (@var{x},@var{y}).

If the point @math{(x,y)} lies inside the valid ranges of the
histogram then the function returns zero to indicate success.  If
@math{(x,y)} lies outside the limits of the histogram then the
function returns @code{GSL_EDOM}, and none of bins are modified.  The
error handler is not called, since it is often necessary to compute
histogram for a small range of a larger dataset, ignoring any
coordinates outside the range of interest.
@end deftypefun

@deftypefun int gsl_histogram2d_accumulate (gsl_histogram2d * @var{h}, double @var{x}, double @var{y}, double @var{weight})
This function is similar to @code{gsl_histogram2d_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_histogram2d_get (const gsl_histogram2d * @var{h}, size_t @var{i}, size_t @var{j})
This function returns the contents of the (@var{i},@var{j})th bin of the
histogram @var{h}.  If (@var{i},@var{j}) 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_histogram2d_get_xrange (const gsl_histogram2d * @var{h}, size_t @var{i}, double * @var{xlower}, double * @var{xupper})
@deftypefunx int gsl_histogram2d_get_yrange (const gsl_histogram2d * @var{h}, size_t @var{j}, double * @var{ylower}, double * @var{yupper})
These functions find the upper and lower range limits of the @var{i}th
and @var{j}th bins in the x and y directions of the histogram @var{h}.
The range limits are stored in @var{xlower} and @var{xupper} or
@var{ylower} and @var{yupper}.  The lower limits are inclusive
(i.e. events with these coordinates are included in the bin) and the
upper limits are exclusive (i.e. events with the value of the upper
limit are not included and fall in the neighboring higher bin, if it
exists).  The functions return 0 to indicate success.  If @var{i} or
@var{j} lies outside the valid range of indices for the histogram then
the error handler is called with an error code of @code{GSL_EDOM}.
@end deftypefun

@deftypefun double gsl_histogram2d_xmax (const gsl_histogram2d * @var{h})
@deftypefunx double gsl_histogram2d_xmin (const gsl_histogram2d * @var{h})
@deftypefunx size_t gsl_histogram2d_nx (const gsl_histogram2d * @var{h})
@deftypefunx double gsl_histogram2d_ymax (const gsl_histogram2d * @var{h})
@deftypefunx double gsl_histogram2d_ymin (const gsl_histogram2d * @var{h})
@deftypefunx size_t gsl_histogram2d_ny (const gsl_histogram2d * @var{h})
These functions return the maximum upper and minimum lower range limits
and the number of bins for the x and y directions of the histogram
@var{h}.  They provide a way of determining these values without
accessing the @code{gsl_histogram2d} struct directly.
@end deftypefun

@deftypefun void gsl_histogram2d_reset (gsl_histogram2d * @var{h})
This function resets all the bins of the histogram @var{h} to zero.
@end deftypefun

@node Searching 2D histogram ranges
@section Searching 2D histogram ranges

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

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

@node 2D Histogram Statistics
@section 2D Histogram Statistics

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

@deftypefun void gsl_histogram2d_max_bin (const gsl_histogram2d * @var{h}, size_t * @var{i}, size_t * @var{j})