histogram.texi

开放gsl矩阵运算

This function returns the indices (@var{i},@var{j}) of the bin
containing the maximum value in the histogram @var{h}. In the case where
several bins contain the same maximum value the first bin found is
returned.
@end deftypefun

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

@deftypefun void gsl_histogram2d_min_bin (const gsl_histogram2d * @var{h}, size_t * @var{i}, size_t * @var{j})
This function returns the indices (@var{i},@var{j}) of the bin
containing the minimum value in the histogram @var{h}. In the case where
several bins contain the same maximum value the first bin found is
returned.
@end deftypefun

@comment @deftypefun double gsl_histogram2d_mean (const gsl_histogram2d * @var{h})
@comment This function returns the mean of the histogrammed variable, where the
@comment histogram is regarded as a probability distribution. Negative bin values
@comment are ignored for the purposes of this calculation.
@comment @end deftypefun

@comment @deftypefun double gsl_histogram2d_sigma (const gsl_histogram2d * @var{h})
@comment This function returns the standard deviation of the histogrammed
@comment variable, where the histogram is regarded as a probability
@comment distribution. Negative bin values are ignored for the purposes of this
@comment calculation.
@comment @end deftypefun

@node 2D Histogram Operations
@section 2D Histogram Operations

@deftypefun int gsl_histogram2d_equal_bins_p (const gsl_histogram2d *@var{h1}, const gsl_histogram2d *@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_histogram2d_add (gsl_histogram2d *@var{h1}, const gsl_histogram2d *@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,j) = h_1(i,j) + h_2(i,j)}.
The two histograms must have identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram2d_sub (gsl_histogram2d *@var{h1}, const gsl_histogram2d *@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,j) = h_1(i,j) - h_2(i,j)}.
The two histograms must have identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram2d_mul (gsl_histogram2d *@var{h1}, const gsl_histogram2d *@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,j) = h_1(i,j) * h_2(i,j)}.
The two histograms must have identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram2d_div (gsl_histogram2d *@var{h1}, const gsl_histogram2d *@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,j) = h_1(i,j) / h_2(i,j)}.
The two histograms must have identical bin ranges.
@end deftypefun

@deftypefun int gsl_histogram2d_scale (gsl_histogram2d *@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,j) = h_1(i,j) * \hbox{\it scale}$}
@math{h'_1(i,j) = h_1(i,j) scale}.
@end deftypefun

@deftypefun int gsl_histogram2d_shift (gsl_histogram2d *@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,j) = h_1(i,j) + \hbox{\it offset}$}
@math{h'_1(i,j) = h_1(i,j) + offset}.
@end deftypefun

@node Reading and writing 2D histograms
@section Reading and writing 2D histograms

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

@deftypefun int gsl_histogram2d_fwrite (FILE * @var{stream}, const gsl_histogram2d * @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_histogram2d_fread (FILE * @var{stream}, gsl_histogram2d * @var{h})
This function reads into the histogram @var{h} from the stream
@var{stream} in binary format.  The histogram @var{h} must be
preallocated with the correct size since the function uses the number of
x and y 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_histogram2d_fprintf (FILE * @var{stream}, const gsl_histogram2d * @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 five columns, and the columns are separated by spaces,
like this,

@smallexample
xrange[0] xrange[1] yrange[0] yrange[1] bin(0,0)
xrange[0] xrange[1] yrange[1] yrange[2] bin(0,1)
xrange[0] xrange[1] yrange[2] yrange[3] bin(0,2)
....
xrange[0] xrange[1] yrange[ny-1] yrange[ny] bin(0,ny-1)

xrange[1] xrange[2] yrange[0] yrange[1] bin(1,0)
xrange[1] xrange[2] yrange[1] yrange[2] bin(1,1)
xrange[1] xrange[2] yrange[1] yrange[2] bin(1,2)
....
xrange[1] xrange[2] yrange[ny-1] yrange[ny] bin(1,ny-1)

....

xrange[nx-1] xrange[nx] yrange[0] yrange[1] bin(nx-1,0)
xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,1)
xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,2)
....
xrange[nx-1] xrange[nx] yrange[ny-1] yrange[ny] bin(nx-1,ny-1)
@end smallexample

@noindent
Each line contains the lower and upper limits of the bin and the
contents of the bin.  Since the upper limits of the each bin are the
lower limits of the neighboring bins there is duplication of these
values but this allows the histogram to be manipulated with
line-oriented tools.
@end deftypefun

@deftypefun int gsl_histogram2d_fscanf (FILE * @var{stream}, gsl_histogram2d * @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 five-column format
used by @code{gsl_histogram_fprintf}.  The histogram @var{h} must be
preallocated with the correct lengths since the function uses the sizes
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 2D histograms
@section Resampling from 2D histograms

As in the one-dimensional case, a two-dimensional 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 (@math{x},@math{y}) falls in
the range of that bin.  For a two-dimensional histogram the probability
distribution takes the form @math{p(x,y) dx dy} where,

@tex
\beforedisplay
$$
p(x,y) = n_{ij}/ (N A_{ij})
$$
\afterdisplay
@end tex
@ifinfo
@example
p(x,y) = n_@{ij@}/ (N A_@{ij@})
@end example
@end ifinfo

@noindent
In this equation 
@c{$n_{ij}$}
@math{n_@{ij@}} is the number of events in the bin which
contains @math{(x,y)}, 
@c{$A_{ij}$}
@math{A_@{ij@}} is the area of the bin and @math{N} is
the total number of events.  The distribution of events within each bin
is assumed to be uniform.

@deftp {Data Type} {gsl_histogram2d_pdf}
@table @code
@item size_t nx, ny
This is the number of histogram bins used to approximate the probability
distribution function 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 * sum
The cumulative probability for the bins is stored in an array of
@var{nx}*@var{ny} elements pointed to by @var{sum}.
@end table
@end deftp
@comment 
@noindent
The following functions allow you to create a @code{gsl_histogram2d_pdf}
struct which represents a two dimensional probability distribution and
generate random samples from it.

@deftypefun {gsl_histogram2d_pdf *} gsl_histogram2d_pdf_alloc (size_t nx, size_t ny)
This function allocates memory for a two-dimensional probability
distribution of size @var{nx}-by-@var{ny} and returns a pointer to a
newly initialized @code{gsl_histogram2d_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_histogram2d_pdf_init (gsl_histogram2d_pdf * @var{p}, const gsl_histogram2d * @var{h})
This function initializes the two-dimensional probability distribution
calculated @var{p} from 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_histogram2d_pdf_free (gsl_histogram2d_pdf * @var{p})
This function frees the two-dimensional probability distribution
function @var{p} and all of the memory associated with it.
@end deftypefun

@deftypefun int gsl_histogram2d_pdf_sample (const gsl_histogram2d_pdf * @var{p}, double @var{r1}, double @var{r2}, double * @var{x}, double * @var{y})
This function uses two uniform random numbers between zero and one,
@var{r1} and @var{r2}, to compute a single random sample from the
two-dimensional probability distribution @var{p}.
@end deftypefun

@node Example programs for 2D histograms
@section Example programs for 2D histograms
This program demonstrates two features of two-dimensional histograms.
First a 10 by 10 2d-histogram is created with x and y running from 0 to
1.  Then a few sample points are added to the histogram, at (0.3,0.3)
with a height of 1, at (0.8,0.1) with a height of 5 and at (0.7,0.9)
with a height of 0.5.  This histogram with three events is used to
generate a random sample of 1000 simulated events, which are printed
out.

@example
#include <stdio.h>
#include <gsl/gsl_rng.h>
#include <gsl/gsl_histogram2d.h>

int
main (void)
@{
  const gsl_rng_type * T;
  gsl_rng * r;

  gsl_histogram2d * h = gsl_histogram2d_alloc (10, 10)

  gsl_histogram2d_set_ranges_uniform (h, 
                                      0.0, 1.0,
                                      0.0, 1.0);

  gsl_histogram2d_accumulate (h, 0.3, 0.3, 1);
  gsl_histogram2d_accumulate (h, 0.8, 0.1, 5);
  gsl_histogram2d_accumulate (h, 0.7, 0.9, 0.5);

  gsl_rng_env_setup();
  
  T = gsl_rng_default;
  r = gsl_rng_alloc(T);

  @{
    int i;
    gsl_histogram2d_pdf * p 
      = gsl_histogram2d_pdf_alloc (h->n);
    
    gsl_histogram2d_pdf_init (p, h);

    for (i = 0; i < 1000; i++) @{
      double x, y;
      double u = gsl_rng_uniform (r);
      double v = gsl_rng_uniform (r);
       
      int status 
       = gsl_histogram2d_pdf_sample (p, u, v, &x, &y);
      
      printf("%g %g\n", x, y);
    @}
  @}
  
 return 0;
@}
@end example
@noindent
The following plot shows the distribution of the simulated events.  Using
a higher resolution grid we can see the original underlying histogram
and also the statistical fluctuations caused by the events being
uniformly distributed over the the area of the original bins.

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