Histograms¶
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 bins which count the number of events falling into a given range of a continuous variable . In GSL the bins of a histogram contain floatingpoint numbers, so they can be used to record both integer and noninteger distributions. The bins can use arbitrary sets of ranges (uniformly spaced bins are the default). Both one and twodimensional 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 on real data.
The functions are declared in the header files gsl_histogram.h
and gsl_histogram2d.h
.
The histogram struct¶
A histogram is defined by the following struct,

gsl_histogram
¶ size_t n This is the number of histogram bins double * range The ranges of the bins are stored in an array of n+1
elements pointed to by range.double * bin The counts for each bin are stored in an array of n
elements pointed to bybin
. The bins are floatingpoint numbers, so you can increment them by noninteger values if necessary.The range for
bin[i]
is given byrange[i]
torange[i+1]
. For bins there aren+1
entries in the arrayrange
. 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,Here is a diagram of the correspondence between ranges and bins on the numberline for :
[ bin[0] )[ bin[1] )[ bin[2] )[ bin[3] )[ bin[4] )  x r[0] r[1] r[2] r[3] r[4] r[5]
In this picture the values of the
range
array are denoted by . On the lefthand side of each bin the square bracket[
denotes an inclusive lower bound (), and the round parentheses)
on the righthand side denote an exclusive upper bound (). 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
gsl_histogram
struct and its associated functions are defined in the header filegsl_histogram.h
.
Histogram allocation¶
The functions for allocating memory to a histogram follow the style of
malloc()
and 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 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 alloc
.

gsl_histogram *
gsl_histogram_alloc
(size_t n)¶ This function allocates memory for a histogram with
n
bins, and returns a pointer to a newly createdgsl_histogram
struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code ofGSL_ENOMEM
. The bins and ranges are not initialized, and should be prepared using one of the rangesetting functions below in order to make the histogram ready for use.

int
gsl_histogram_set_ranges
(gsl_histogram * h, const double range[], size_t size)¶ This function sets the ranges of the existing histogram
h
using the arrayrange
of sizesize
. The values of the histogram bins are reset to zero. Therange
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):
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);
Note that the size of the
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.

int
gsl_histogram_set_ranges_uniform
(gsl_histogram * h, double xmin, double xmax)¶ This function sets the ranges of the existing histogram
h
to cover the rangexmin
toxmax
uniformly. The values of the histogram bins are reset to zero. The bin ranges are shown in the table below,where is the bin spacing, .

void
gsl_histogram_free
(gsl_histogram * h)¶ This function frees the histogram
h
and all of the memory associated with it.
Copying Histograms¶

int
gsl_histogram_memcpy
(gsl_histogram * dest, const gsl_histogram * src)¶ This function copies the histogram
src
into the preexisting histogramdest
, makingdest
into an exact copy ofsrc
. The two histograms must be of the same size.

gsl_histogram *
gsl_histogram_clone
(const gsl_histogram * src)¶ This function returns a pointer to a newly created histogram which is an exact copy of the histogram
src
.
Updating and accessing histogram elements¶
There are two ways to access histogram bins, either by specifying an coordinate or by using the binindex directly. The functions for accessing the histogram through coordinates use a binary search to identify the bin which covers the appropriate range.

int
gsl_histogram_increment
(gsl_histogram * h, double x)¶ This function updates the histogram
h
by adding one (1.0) to the bin whose range contains the coordinatex
.If
x
lies in the valid range of the histogram then the function returns zero to indicate success. Ifx
is less than the lower limit of the histogram then the function returnsGSL_EDOM
, and none of bins are modified. Similarly, if the value ofx
is greater than or equal to the upper limit of the histogram then the function returnsGSL_EDOM
, and none of the bins are modified. The error handler is not called, however, since it is often necessary to compute histograms for a small range of a larger dataset, ignoring the values outside the range of interest.

int
gsl_histogram_accumulate
(gsl_histogram * h, double x, double weight)¶ This function is similar to
gsl_histogram_increment()
but increases the value of the appropriate bin in the histogramh
by the floatingpoint numberweight
.

double
gsl_histogram_get
(const gsl_histogram * h, size_t i)¶ This function returns the contents of the
i
th bin of the histogramh
. Ifi
lies outside the valid range of indices for the histogram then the error handler is called with an error code ofGSL_EDOM
and the function returns 0.

int
gsl_histogram_get_range
(const gsl_histogram * h, size_t i, double * lower, double * upper)¶ This function finds the upper and lower range limits of the
i
th bin of the histogramh
. If the indexi
is valid then the corresponding range limits are stored inlower
andupper
. 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. Ifi
lies outside the valid range of indices for the histogram then the error handler is called and the function returns an error code ofGSL_EDOM
.

double
gsl_histogram_max
(const gsl_histogram * h)¶ 
double
gsl_histogram_min
(const gsl_histogram * h)¶ 
size_t
gsl_histogram_bins
(const gsl_histogram * h)¶ These functions return the maximum upper and minimum lower range limits and the number of bins of the histogram
h
. They provide a way of determining these values without accessing thegsl_histogram
struct directly.

void
gsl_histogram_reset
(gsl_histogram * h)¶ This function resets all the bins in the histogram
h
to zero.
Searching histogram ranges¶
The following functions are used by the access and update routines to locate the bin which corresponds to a given coordinate.

int
gsl_histogram_find
(const gsl_histogram * h, double x, size_t * i)¶ This function finds and sets the index
i
to the bin number which covers the coordinatex
in the histogramh
. 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. Ifx
is found in the range of the histogram then the function sets the indexi
and returnsGSL_SUCCESS
. Ifx
lies outside the valid range of the histogram then the function returnsGSL_EDOM
and the error handler is invoked.
Histogram Statistics¶

double
gsl_histogram_max_val
(const gsl_histogram * h)¶ This function returns the maximum value contained in the histogram bins.

size_t
gsl_histogram_max_bin
(const gsl_histogram * 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.

double
gsl_histogram_min_val
(const gsl_histogram * h)¶ This function returns the minimum value contained in the histogram bins.

size_t
gsl_histogram_min_bin
(const gsl_histogram * 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.

double
gsl_histogram_mean
(const gsl_histogram * 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.

double
gsl_histogram_sigma
(const gsl_histogram * 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.

double
gsl_histogram_sum
(const gsl_histogram * h)¶ This function returns the sum of all bin values. Negative bin values are included in the sum.
Histogram Operations¶

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

int
gsl_histogram_add
(gsl_histogram * h1, const gsl_histogram * h2)¶ This function adds the contents of the bins in histogram
h2
to the corresponding bins of histogramh1
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram_sub
(gsl_histogram * h1, const gsl_histogram * h2)¶ This function subtracts the contents of the bins in histogram
h2
from the corresponding bins of histogramh1
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram_mul
(gsl_histogram * h1, const gsl_histogram * h2)¶ This function multiplies the contents of the bins of histogram
h1
by the contents of the corresponding bins in histogramh2
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram_div
(gsl_histogram * h1, const gsl_histogram * h2)¶ This function divides the contents of the bins of histogram
h1
by the contents of the corresponding bins in histogramh2
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram_scale
(gsl_histogram * h, double scale)¶ This function multiplies the contents of the bins of histogram
h
by the constantscale
, i.e.

int
gsl_histogram_shift
(gsl_histogram * h, double offset)¶ This function shifts the contents of the bins of histogram
h
by the constantoffset
, i.e.
Reading and writing histograms¶
The library provides functions for reading and writing histograms to a file as binary data or formatted text.

int
gsl_histogram_fwrite
(FILE * stream, const gsl_histogram * h)¶ This function writes the ranges and bins of the histogram
h
to the streamstream
in binary format. The return value is 0 for success andGSL_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.

int
gsl_histogram_fread
(FILE * stream, gsl_histogram * h)¶ This function reads into the histogram
h
from the open streamstream
in binary format. The histogramh
must be preallocated with the correct size since the function uses the number of bins inh
to determine how many bytes to read. The return value is 0 for success andGSL_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.

int
gsl_histogram_fprintf
(FILE * stream, const gsl_histogram * h, const char * range_format, const char * bin_format)¶ This function writes the ranges and bins of the histogram
h
linebyline to the streamstream
using the format specifiersrange_format
andbin_format
. These should be one of the%g
,%e
or%f
formats for floating point numbers. The function returns 0 for success andGSL_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:range[0] range[1] bin[0] range[1] range[2] bin[1] range[2] range[3] bin[2] .... range[n1] range[n] bin[n1]
The values of the ranges are formatted using
range_format
and the value of the bins are formatted usingbin_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 lineoriented tools.

int
gsl_histogram_fscanf
(FILE * stream, gsl_histogram * h)¶ This function reads formatted data from the stream
stream
into the histogramh
. The data is assumed to be in the threecolumn format used bygsl_histogram_fprintf()
. The histogramh
must be preallocated with the correct length since the function uses the size ofh
to determine how many numbers to read. The function returns 0 for success andGSL_EFAILED
if there was a problem reading from the file.
Resampling 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 falls in the range of that bin. The probability distribution function has the onedimensional form where,
In this equation is the number of events in the bin which contains , is the width of the bin and is the total number of events. The distribution of events within each bin is assumed to be uniform.
The histogram probability distribution struct¶
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 . 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 onetoone 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.

gsl_histogram_pdf
¶ size_t n
This is the number of bins used to approximate the probability distribution function. double * range
The ranges of the bins are stored in an array of elements pointed to by range
.double * sum
The cumulative probability for the bins is stored in an array of n
elements pointed to bysum
.
The following functions allow you to create a gsl_histogram_pdf
struct which represents this probability distribution and generate
random samples from it.

gsl_histogram_pdf *
gsl_histogram_pdf_alloc
(size_t n)¶ This function allocates memory for a probability distribution with
n
bins and returns a pointer to a newly initializedgsl_histogram_pdf
struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code ofGSL_ENOMEM
.

int
gsl_histogram_pdf_init
(gsl_histogram_pdf * p, const gsl_histogram * h)¶ This function initializes the probability distribution
p
with the contents of the histogramh
. If any of the bins ofh
are negative then the error handler is invoked with an error code ofGSL_EDOM
because a probability distribution cannot contain negative values.

void
gsl_histogram_pdf_free
(gsl_histogram_pdf * p)¶ This function frees the probability distribution function
p
and all of the memory associated with it.

double
gsl_histogram_pdf_sample
(const gsl_histogram_pdf * p, double r)¶ This function uses
r
, a uniform random number between zero and one, to compute a single random sample from the probability distributionp
. The algorithm used to compute the sample is given by the following formula,where is the index which satisfies and is .
Example programs for histograms¶
The following program shows how to make a simple histogram of a column
of numerical data supplied on 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 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
gsl_histogram_fprintf()
.
#include <stdio.h>
#include <stdlib.h>
#include <gsl/gsl_histogram.h>
int
main (int argc, char **argv)
{
double a, b;
size_t n;
if (argc != 4)
{
printf ("Usage: gslhistogram 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]);
{
double x;
gsl_histogram * h = gsl_histogram_alloc (n);
gsl_histogram_set_ranges_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);
}
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:
$ gslrandist 0 10000 cauchy 30
 gslhistogram  100 100 200 > histogram.dat
Fig. 12 shows the familiar shape of the Cauchy distribution and the fluctuations caused by the finite sample size.
Two dimensional histograms¶
A two dimensional histogram consists of a set of bins which count the number of events falling in a given area of the plane. The simplest way to use a two dimensional histogram is to record twodimensional position information, . Another possibility is to form a joint distribution by recording related variables. For example a detector might record both the position of an event () and the amount of energy it deposited . These could be histogrammed as the joint distribution .
The 2D histogram struct¶
Two dimensional histograms are defined by the following struct,

gsl_histogram2d
¶ size_t nx, ny
This is the number of histogram bins in the x and y directions. double * xrange
The ranges of the bins in the xdirection are stored in an array of nx + 1
elements pointed to byxrange
.double * yrange
The ranges of the bins in the ydirection are stored in an array of ny + 1
elements pointed to byyrange
.double * bin
The counts for each bin are stored in an array pointed to by bin
. The bins are floatingpoint numbers, so you can increment them by noninteger values if necessary. The arraybin
stores the two dimensional array of bins in a single block of memory according to the mappingbin(i,j)
=bin[i * ny + j]
.
The range for bin(i,j)
is given by xrange[i]
to
xrange[i+1]
in the xdirection and yrange[j]
to
yrange[j+1]
in the ydirection. 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,
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 gsl_histogram2d
struct and its associated functions are
defined in the header file gsl_histogram2d.h
.
2D Histogram allocation¶
The functions for allocating memory to a 2D histogram follow the style
of malloc()
and 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 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 alloc
.

gsl_histogram2d *
gsl_histogram2d_alloc
(size_t nx, size_t ny)¶ This function allocates memory for a twodimensional histogram with
nx
bins in the x direction andny
bins in the y direction. The function returns a pointer to a newly createdgsl_histogram2d
struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code ofGSL_ENOMEM
. The bins and ranges must be initialized with one of the functions below before the histogram is ready for use.

int
gsl_histogram2d_set_ranges
(gsl_histogram2d * h, const double xrange[], size_t xsize, const double yrange[], size_t ysize)¶ This function sets the ranges of the existing histogram
h
using the arraysxrange
andyrange
of sizexsize
andysize
respectively. The values of the histogram bins are reset to zero.

int
gsl_histogram2d_set_ranges_uniform
(gsl_histogram2d * h, double xmin, double xmax, double ymin, double ymax)¶ This function sets the ranges of the existing histogram
h
to cover the rangesxmin
toxmax
andymin
toymax
uniformly. The values of the histogram bins are reset to zero.

void
gsl_histogram2d_free
(gsl_histogram2d * h)¶ This function frees the 2D histogram
h
and all of the memory associated with it.
Copying 2D Histograms¶

int
gsl_histogram2d_memcpy
(gsl_histogram2d * dest, const gsl_histogram2d * src)¶ This function copies the histogram
src
into the preexisting histogramdest
, makingdest
into an exact copy ofsrc
. The two histograms must be of the same size.

gsl_histogram2d *
gsl_histogram2d_clone
(const gsl_histogram2d * src)¶ This function returns a pointer to a newly created histogram which is an exact copy of the histogram
src
.
Updating and accessing 2D histogram elements¶
You can access the bins of a twodimensional histogram either by specifying a pair of coordinates or by using the bin indices directly. The functions for accessing the histogram through coordinates use binary searches in the x and y directions to identify the bin which covers the appropriate range.

int
gsl_histogram2d_increment
(gsl_histogram2d * h, double x, double y)¶ This function updates the histogram
h
by adding one (1.0) to the bin whose x and y ranges contain the coordinates (x
,y
).If the point lies inside the valid ranges of the histogram then the function returns zero to indicate success. If lies outside the limits of the histogram then the function returns
GSL_EDOM
, and none of the bins are modified. The error handler is not called, since it is often necessary to compute histograms for a small range of a larger dataset, ignoring any coordinates outside the range of interest.

int
gsl_histogram2d_accumulate
(gsl_histogram2d * h, double x, double y, double weight)¶ This function is similar to
gsl_histogram2d_increment()
but increases the value of the appropriate bin in the histogramh
by the floatingpoint numberweight
.

double
gsl_histogram2d_get
(const gsl_histogram2d * h, size_t i, size_t j)¶ This function returns the contents of the (
i
,j
)th bin of the histogramh
. If (i
,j
) lies outside the valid range of indices for the histogram then the error handler is called with an error code ofGSL_EDOM
and the function returns 0.

int
gsl_histogram2d_get_xrange
(const gsl_histogram2d * h, size_t i, double * xlower, double * xupper)¶ 
int
gsl_histogram2d_get_yrange
(const gsl_histogram2d * h, size_t j, double * ylower, double * yupper)¶ These functions find the upper and lower range limits of the
i
th andj
th bins in the x and y directions of the histogramh
. The range limits are stored inxlower
andxupper
orylower
andyupper
. 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. Ifi
orj
lies outside the valid range of indices for the histogram then the error handler is called with an error code ofGSL_EDOM
.

double
gsl_histogram2d_xmax
(const gsl_histogram2d * h)¶ 
double
gsl_histogram2d_xmin
(const gsl_histogram2d * h)¶ 
size_t
gsl_histogram2d_nx
(const gsl_histogram2d * h)¶ 
double
gsl_histogram2d_ymax
(const gsl_histogram2d * h)¶ 
double
gsl_histogram2d_ymin
(const gsl_histogram2d * h)¶ 
size_t
gsl_histogram2d_ny
(const gsl_histogram2d * 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
h
. They provide a way of determining these values without accessing thegsl_histogram2d
struct directly.

void
gsl_histogram2d_reset
(gsl_histogram2d * h)¶ This function resets all the bins of the histogram
h
to zero.
Searching 2D histogram ranges¶
The following functions are used by the access and update routines to locate the bin which corresponds to a given coordinate.

int
gsl_histogram2d_find
(const gsl_histogram2d * h, double x, double y, size_t * i, size_t * j)¶ This function finds and sets the indices
i
andj
to the bin which covers the coordinates (x
,y
). The bin is located using a binary search. The search includes an optimization for histograms with uniform ranges, and will return the correct bin immediately in this case. If is found then the function sets the indices (i
,j
) and returnsGSL_SUCCESS
. If lies outside the valid range of the histogram then the function returnsGSL_EDOM
and the error handler is invoked.
2D Histogram Statistics¶

double
gsl_histogram2d_max_val
(const gsl_histogram2d * h)¶ This function returns the maximum value contained in the histogram bins.

void
gsl_histogram2d_max_bin
(const gsl_histogram2d * h, size_t * i, size_t * j)¶ This function finds the indices of the bin containing the maximum value in the histogram
h
and stores the result in (i
,j
). In the case where several bins contain the same maximum value the first bin found is returned.

double
gsl_histogram2d_min_val
(const gsl_histogram2d * h)¶ This function returns the minimum value contained in the histogram bins.

void
gsl_histogram2d_min_bin
(const gsl_histogram2d * h, size_t * i, size_t * j)¶ This function finds the indices of the bin containing the minimum value in the histogram
h
and stores the result in (i
,j
). In the case where several bins contain the same maximum value the first bin found is returned.

double
gsl_histogram2d_xmean
(const gsl_histogram2d * h)¶ This function returns the mean of the histogrammed x variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

double
gsl_histogram2d_ymean
(const gsl_histogram2d * h)¶ This function returns the mean of the histogrammed y variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

double
gsl_histogram2d_xsigma
(const gsl_histogram2d * h)¶ This function returns the standard deviation of the histogrammed x variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

double
gsl_histogram2d_ysigma
(const gsl_histogram2d * h)¶ This function returns the standard deviation of the histogrammed y variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

double
gsl_histogram2d_cov
(const gsl_histogram2d * h)¶ This function returns the covariance of the histogrammed x and y variables, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation.

double
gsl_histogram2d_sum
(const gsl_histogram2d * h)¶ This function returns the sum of all bin values. Negative bin values are included in the sum.
2D Histogram Operations¶

int
gsl_histogram2d_equal_bins_p
(const gsl_histogram2d * h1, const gsl_histogram2d * h2)¶ This function returns 1 if all the individual bin ranges of the two histograms are identical, and 0 otherwise.

int
gsl_histogram2d_add
(gsl_histogram2d * h1, const gsl_histogram2d * h2)¶ This function adds the contents of the bins in histogram
h2
to the corresponding bins of histogramh1
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram2d_sub
(gsl_histogram2d * h1, const gsl_histogram2d * h2)¶ This function subtracts the contents of the bins in histogram
h2
from the corresponding bins of histogramh1
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram2d_mul
(gsl_histogram2d * h1, const gsl_histogram2d * h2)¶ This function multiplies the contents of the bins of histogram
h1
by the contents of the corresponding bins in histogramh2
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram2d_div
(gsl_histogram2d * h1, const gsl_histogram2d * h2)¶ This function divides the contents of the bins of histogram
h1
by the contents of the corresponding bins in histogramh2
, i.e. . The two histograms must have identical bin ranges.

int
gsl_histogram2d_scale
(gsl_histogram2d * h, double scale)¶ This function multiplies the contents of the bins of histogram
h
by the constantscale
, i.e.

int
gsl_histogram2d_shift
(gsl_histogram2d * h, double offset)¶ This function shifts the contents of the bins of histogram
h
by the constantoffset
, i.e.
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.

int
gsl_histogram2d_fwrite
(FILE * stream, const gsl_histogram2d * h)¶ This function writes the ranges and bins of the histogram
h
to the streamstream
in binary format. The return value is 0 for success andGSL_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.

int
gsl_histogram2d_fread
(FILE * stream, gsl_histogram2d * h)¶ This function reads into the histogram
h
from the streamstream
in binary format. The histogramh
must be preallocated with the correct size since the function uses the number of x and y bins inh
to determine how many bytes to read. The return value is 0 for success andGSL_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.

int
gsl_histogram2d_fprintf
(FILE * stream, const gsl_histogram2d * h, const char * range_format, const char * bin_format)¶ This function writes the ranges and bins of the histogram
h
linebyline to the streamstream
using the format specifiersrange_format
andbin_format
. These should be one of the%g
,%e
or%f
formats for floating point numbers. The function returns 0 for success andGSL_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: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[ny1] yrange[ny] bin(0,ny1) 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[ny1] yrange[ny] bin(1,ny1) .... xrange[nx1] xrange[nx] yrange[0] yrange[1] bin(nx1,0) xrange[nx1] xrange[nx] yrange[1] yrange[2] bin(nx1,1) xrange[nx1] xrange[nx] yrange[1] yrange[2] bin(nx1,2) .... xrange[nx1] xrange[nx] yrange[ny1] yrange[ny] bin(nx1,ny1)
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 lineoriented tools.

int
gsl_histogram2d_fscanf
(FILE * stream, gsl_histogram2d * h)¶ This function reads formatted data from the stream
stream
into the histogramh
. The data is assumed to be in the fivecolumn format used bygsl_histogram2d_fprintf()
. The histogramh
must be preallocated with the correct lengths since the function uses the sizes ofh
to determine how many numbers to read. The function returns 0 for success andGSL_EFAILED
if there was a problem reading from the file.
Resampling from 2D histograms¶
As in the onedimensional case, a twodimensional 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:y) falls in the range of that bin. For a twodimensional histogram the probability distribution takes the form where,
In this equation is the number of events in the bin which contains , is the area of the bin and is the total number of events. The distribution of events within each bin is assumed to be uniform.

gsl_histogram2d_pdf
¶ size_t nx, ny
This is the number of histogram bins used to approximate the probability distribution function in the x and y directions. double * xrange
The ranges of the bins in the xdirection are stored in an array of nx + 1
elements pointed to byxrange
.double * yrange
The ranges of the bins in the ydirection are stored in an array of ny + 1
pointed to byyrange
.double * sum
The cumulative probability for the bins is stored in an array of nx
*ny
elements pointed to bysum
.
The following functions allow you to create a gsl_histogram2d_pdf
struct which represents a two dimensional probability distribution and
generate random samples from it.

gsl_histogram2d_pdf *
gsl_histogram2d_pdf_alloc
(size_t nx, size_t ny)¶ This function allocates memory for a twodimensional probability distribution of size
nx
byny
and returns a pointer to a newly initializedgsl_histogram2d_pdf
struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code ofGSL_ENOMEM
.

int
gsl_histogram2d_pdf_init
(gsl_histogram2d_pdf * p, const gsl_histogram2d * h)¶ This function initializes the twodimensional probability distribution calculated
p
from the histogramh
. If any of the bins ofh
are negative then the error handler is invoked with an error code ofGSL_EDOM
because a probability distribution cannot contain negative values.

void
gsl_histogram2d_pdf_free
(gsl_histogram2d_pdf * p)¶ This function frees the twodimensional probability distribution function
p
and all of the memory associated with it.

int
gsl_histogram2d_pdf_sample
(const gsl_histogram2d_pdf * p, double r1, double r2, double * x, double * y)¶ This function uses two uniform random numbers between zero and one,
r1
andr2
, to compute a single random sample from the twodimensional probability distributionp
.
Example programs for 2D histograms¶
This program demonstrates two features of twodimensional histograms. First a 10by10 twodimensional 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.
#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>nx, h>ny);
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);
gsl_histogram2d_pdf_sample (p, u, v, &x, &y);
printf ("%g %g\n", x, y);
}
gsl_histogram2d_pdf_free (p);
}
gsl_histogram2d_free (h);
gsl_rng_free (r);
return 0;
}
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 area of the original bins.