File: gsl-ref_21.html

package info (click to toggle)
gsl-ref-html 1.6-1
links: PTS
area: main
in suites: sarge
size: 1,504 kB
ctags: 3,558
sloc: makefile: 36
file content (1538 lines) | stat: -rw-r--r-- 54,122 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.54+ (gsl)
     from ../gsl-ref.texi -->

<TITLE>GNU Scientific Library -- Reference Manual - Histograms</TITLE>
<!-- <LINK rel="stylesheet" title="Default Style Sheet" href="/css/texinfo.css" type="text/css"> -->
<link href="gsl-ref_22.html" rel=Next>
<link href="gsl-ref_20.html" rel=Previous>
<link href="gsl-ref_toc.html" rel=ToC>

</HEAD>
<BODY>
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_20.html">previous</A>, <A HREF="gsl-ref_22.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC338" HREF="gsl-ref_toc.html#TOC338">Histograms</A></H1>
<P>
<A NAME="IDX1722"></A>
<A NAME="IDX1723"></A>
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 <I>bins</I> which count the number
of events falling into a given range of a continuous variable 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.

</P>
<P>
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.

</P>
<P>
The functions are declared in the header files <TT>'gsl_histogram.h'</TT>
and <TT>'gsl_histogram2d.h'</TT>.

</P>



<H2><A NAME="SEC339" HREF="gsl-ref_toc.html#TOC339">The histogram struct</A></H2>

<P>
A histogram is defined by the following struct,

</P>
<P>
<DL>
<DT><U>Data Type:</U> <B>gsl_histogram</B>
<DD><A NAME="IDX1724"></A>
<DL COMPACT>

<DT><CODE>size_t n</CODE>
<DD>
This is the number of histogram bins
<DT><CODE>double * range</CODE>
<DD>
The ranges of the bins are stored in an array of <VAR>n+1</VAR> elements
pointed to by <VAR>range</VAR>.
<DT><CODE>double * bin</CODE>
<DD>
The counts for each bin are stored in an array of <VAR>n</VAR> elements
pointed to by <VAR>bin</VAR>.  The bins are floating-point numbers, so you can
increment them by non-integer values if necessary.
</DL>
</DL>
<P>
The range for <VAR>bin</VAR>[i] is given by <VAR>range</VAR>[i] to
<VAR>range</VAR>[i+1].  For n bins there are n+1 entries in the
array <VAR>range</VAR>.  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,

</P>

<PRE class="display">
bin[i] corresponds to range[i] &#60;= x &#60; range[i+1]
</PRE>

<P>
Here is a diagram of the correspondence between ranges and bins on the
number-line for x,

</P>

<PRE class="smallexample">

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

</PRE>

<P>
In this picture the values of the <VAR>range</VAR> array are denoted by
r.  On the left-hand side of each bin the square bracket
"<CODE>[</CODE>" denotes an inclusive lower bound 
(
r &#60;= x), and the round parentheses "<CODE>)</CODE>" on the right-hand
side denote an exclusive upper bound (x &#60; 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.

</P>
<P>
The <CODE>gsl_histogram</CODE> struct and its associated functions are defined
in the header file <TT>'gsl_histogram.h'</TT>.

</P>


<H2><A NAME="SEC340" HREF="gsl-ref_toc.html#TOC340">Histogram allocation</A></H2>
<P>
The functions for allocating memory to a histogram follow the style of
<CODE>malloc</CODE> and <CODE>free</CODE>.  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</CODE>) 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</CODE>.

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_histogram * <B>gsl_histogram_alloc</B> <I>(size_t <VAR>n</VAR>)</I>
<DD><A NAME="IDX1725"></A>
This function allocates memory for a histogram with <VAR>n</VAR> bins, and
returns a pointer to a newly created <CODE>gsl_histogram</CODE> 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</CODE>. 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.
</DL>

</P>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_set_ranges</B> <I>(gsl_histogram * <VAR>h</VAR>, const double <VAR>range</VAR>[], size_t <VAR>size</VAR>)</I>
<DD><A NAME="IDX1726"></A>
This function sets the ranges of the existing histogram <VAR>h</VAR> using
the array <VAR>range</VAR> of size <VAR>size</VAR>.  The values of the histogram
bins are reset to zero.  The <CODE>range</CODE> array should contain the
desired bin limits.  The ranges can be arbitrary, subject to the
restriction that they are monotonically increasing.

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

</P>

<PRE class="example">
gsl_histogram * h = gsl_histogram_alloc (3);

/* bin[0] covers the range 1 &#60;= x &#60; 10 */
/* bin[1] covers the range 10 &#60;= x &#60; 100 */
/* bin[2] covers the range 100 &#60;= x &#60; 1000 */

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

gsl_histogram_set_ranges (h, range, 4);
</PRE>

<P>
Note that the size of the <VAR>range</VAR> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_set_ranges_uniform</B> <I>(gsl_histogram * <VAR>h</VAR>, double <VAR>xmin</VAR>, double <VAR>xmax</VAR>)</I>
<DD><A NAME="IDX1727"></A>
This function sets the ranges of the existing histogram <VAR>h</VAR> to cover
the range <VAR>xmin</VAR> to <VAR>xmax</VAR> uniformly.  The values of the
histogram bins are reset to zero.  The bin ranges are shown in the table
below,

</P>

<PRE class="display">
bin[0] corresponds to xmin &#60;= x &#60; xmin + d
bin[1] corresponds to xmin + d &#60;= x &#60; xmin + 2 d
......
bin[n-1] corresponds to xmin + (n-1)d &#60;= x &#60; xmax
</PRE>

<P>
where d is the bin spacing, d = (xmax-xmin)/n.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram_free</B> <I>(gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1728"></A>
This function frees the histogram <VAR>h</VAR> and all of the memory
associated with it.
</DL>

</P>


<H2><A NAME="SEC341" HREF="gsl-ref_toc.html#TOC341">Copying Histograms</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_memcpy</B> <I>(gsl_histogram * <VAR>dest</VAR>, const gsl_histogram * <VAR>src</VAR>)</I>
<DD><A NAME="IDX1729"></A>
This function copies the histogram <VAR>src</VAR> into the pre-existing
histogram <VAR>dest</VAR>, making <VAR>dest</VAR> into an exact copy of <VAR>src</VAR>.
The two histograms must be of the same size.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_histogram * <B>gsl_histogram_clone</B> <I>(const gsl_histogram * <VAR>src</VAR>)</I>
<DD><A NAME="IDX1730"></A>
This function returns a pointer to a newly created histogram which is an
exact copy of the histogram <VAR>src</VAR>.
</DL>

</P>


<H2><A NAME="SEC342" HREF="gsl-ref_toc.html#TOC342">Updating and accessing histogram elements</A></H2>

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

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_increment</B> <I>(gsl_histogram * <VAR>h</VAR>, double <VAR>x</VAR>)</I>
<DD><A NAME="IDX1731"></A>
This function updates the histogram <VAR>h</VAR> by adding one (1.0) to the
bin whose range contains the coordinate <VAR>x</VAR>. 

</P>
<P>
If <VAR>x</VAR> lies in the valid range of the histogram then the function
returns zero to indicate success.  If <VAR>x</VAR> is less than the lower
limit of the histogram then the function returns <CODE>GSL_EDOM</CODE>, and
none of bins are modified.  Similarly, if the value of <VAR>x</VAR> is greater
than or equal to the upper limit of the histogram then the function
returns <CODE>GSL_EDOM</CODE>, 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_accumulate</B> <I>(gsl_histogram * <VAR>h</VAR>, double <VAR>x</VAR>, double <VAR>weight</VAR>)</I>
<DD><A NAME="IDX1732"></A>
This function is similar to <CODE>gsl_histogram_increment</CODE> but increases
the value of the appropriate bin in the histogram <VAR>h</VAR> by the
floating-point number <VAR>weight</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_get</B> <I>(const gsl_histogram * <VAR>h</VAR>, size_t <VAR>i</VAR>)</I>
<DD><A NAME="IDX1733"></A>
This function returns the contents of the <VAR>i</VAR>-th bin of the histogram
<VAR>h</VAR>.  If <VAR>i</VAR> lies outside the valid range of indices for the
histogram then the error handler is called with an error code of
<CODE>GSL_EDOM</CODE> and the function returns 0.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_get_range</B> <I>(const gsl_histogram * <VAR>h</VAR>, size_t <VAR>i</VAR>, double * <VAR>lower</VAR>, double * <VAR>upper</VAR>)</I>
<DD><A NAME="IDX1734"></A>
This function finds the upper and lower range limits of the <VAR>i</VAR>-th
bin of the histogram <VAR>h</VAR>.  If the index <VAR>i</VAR> is valid then the
corresponding range limits are stored in <VAR>lower</VAR> and <VAR>upper</VAR>.
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</VAR> 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</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_max</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1735"></A>
<DT><U>Function:</U> double <B>gsl_histogram_min</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1736"></A>
<DT><U>Function:</U> size_t <B>gsl_histogram_bins</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1737"></A>
These functions return the maximum upper and minimum lower range limits
and the number of bins of the histogram <VAR>h</VAR>.  They provide a way of
determining these values without accessing the <CODE>gsl_histogram</CODE>
struct directly.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram_reset</B> <I>(gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1738"></A>
This function resets all the bins in the histogram <VAR>h</VAR> to zero.
</DL>

</P>


<H2><A NAME="SEC343" HREF="gsl-ref_toc.html#TOC343">Searching histogram ranges</A></H2>

<P>
The following functions are used by the access and update routines to
locate the bin which corresponds to a given x coordinate.

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_find</B> <I>(const gsl_histogram * <VAR>h</VAR>, double <VAR>x</VAR>, size_t * <VAR>i</VAR>)</I>
<DD><A NAME="IDX1739"></A>
This function finds and sets the index <VAR>i</VAR> to the bin number which
covers the coordinate <VAR>x</VAR> in the histogram <VAR>h</VAR>.  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</VAR> is found in the range of the
histogram then the function sets the index <VAR>i</VAR> and returns
<CODE>GSL_SUCCESS</CODE>.  If <VAR>x</VAR> lies outside the valid range of the
histogram then the function returns <CODE>GSL_EDOM</CODE> and the error
handler is invoked.
</DL>

</P>


<H2><A NAME="SEC344" HREF="gsl-ref_toc.html#TOC344">Histogram Statistics</A></H2>
<P>
<A NAME="IDX1740"></A>
<A NAME="IDX1741"></A>
<A NAME="IDX1742"></A>
<A NAME="IDX1743"></A>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_max_val</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1744"></A>
This function returns the maximum value contained in the histogram bins.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_histogram_max_bin</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1745"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_min_val</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1746"></A>
This function returns the minimum value contained in the histogram bins.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> size_t <B>gsl_histogram_min_bin</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1747"></A>
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.
</DL>

</P>
<P>
<A NAME="IDX1748"></A>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_mean</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1749"></A>
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.
</DL>

</P>
<P>
<A NAME="IDX1750"></A>
<A NAME="IDX1751"></A>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_sigma</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1752"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_sum</B> <I>(const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1753"></A>
This function returns the sum of all bin values. Negative bin values
are included in the sum.
</DL>

</P>


<H2><A NAME="SEC345" HREF="gsl-ref_toc.html#TOC345">Histogram Operations</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_equal_bins_p</B> <I>(const gsl_histogram *<VAR>h1</VAR>, const gsl_histogram *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1754"></A>
This function returns 1 if the all of the individual bin
ranges of the two histograms are identical, and 0
otherwise.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_add</B> <I>(gsl_histogram *<VAR>h1</VAR>, const gsl_histogram *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1755"></A>
This function adds the contents of the bins in histogram <VAR>h2</VAR> to the
corresponding bins of histogram <VAR>h1</VAR>,  i.e. h'_1(i) = h_1(i) +
h_2(i).  The two histograms must have identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_sub</B> <I>(gsl_histogram *<VAR>h1</VAR>, const gsl_histogram *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1756"></A>
This function subtracts the contents of the bins in histogram <VAR>h2</VAR>
from the corresponding bins of histogram <VAR>h1</VAR>, i.e. h'_1(i) =
h_1(i) - h_2(i).  The two histograms must have identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_mul</B> <I>(gsl_histogram *<VAR>h1</VAR>, const gsl_histogram *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1757"></A>
This function multiplies the contents of the bins of histogram <VAR>h1</VAR>
by the contents of the corresponding bins in histogram <VAR>h2</VAR>,
i.e. h'_1(i) = h_1(i) * h_2(i).  The two histograms must have
identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_div</B> <I>(gsl_histogram *<VAR>h1</VAR>, const gsl_histogram *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1758"></A>
This function divides the contents of the bins of histogram <VAR>h1</VAR> by
the contents of the corresponding bins in histogram <VAR>h2</VAR>,
i.e. h'_1(i) = h_1(i) / h_2(i).  The two histograms must have
identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_scale</B> <I>(gsl_histogram *<VAR>h</VAR>, double <VAR>scale</VAR>)</I>
<DD><A NAME="IDX1759"></A>
This function multiplies the contents of the bins of histogram <VAR>h</VAR>
by the constant <VAR>scale</VAR>, i.e. 
h'_1(i) = h_1(i) * scale.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_shift</B> <I>(gsl_histogram *<VAR>h</VAR>, double <VAR>offset</VAR>)</I>
<DD><A NAME="IDX1760"></A>
This function shifts the contents of the bins of histogram <VAR>h</VAR> by
the constant <VAR>offset</VAR>, i.e. 
h'_1(i) = h_1(i) + offset.
</DL>

</P>


<H2><A NAME="SEC346" HREF="gsl-ref_toc.html#TOC346">Reading and writing histograms</A></H2>

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

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_fwrite</B> <I>(FILE * <VAR>stream</VAR>, const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1761"></A>
This function writes the ranges and bins of the histogram <VAR>h</VAR> to the
stream <VAR>stream</VAR> in binary format.  The return value is 0 for success
and <CODE>GSL_EFAILED</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_fread</B> <I>(FILE * <VAR>stream</VAR>, gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1762"></A>
This function reads into the histogram <VAR>h</VAR> from the open stream
<VAR>stream</VAR> in binary format.  The histogram <VAR>h</VAR> must be
preallocated with the correct size since the function uses the number of
bins in <VAR>h</VAR> to determine how many bytes to read.  The return value is
0 for success and <CODE>GSL_EFAILED</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_fprintf</B> <I>(FILE * <VAR>stream</VAR>, const gsl_histogram * <VAR>h</VAR>, const char * <VAR>range_format</VAR>, const char * <VAR>bin_format</VAR>)</I>
<DD><A NAME="IDX1763"></A>
This function writes the ranges and bins of the histogram <VAR>h</VAR>
line-by-line to the stream <VAR>stream</VAR> using the format specifiers
<VAR>range_format</VAR> and <VAR>bin_format</VAR>.  These should be one of the
<CODE>%g</CODE>, <CODE>%e</CODE> or <CODE>%f</CODE> formats for floating point
numbers.  The function returns 0 for success and <CODE>GSL_EFAILED</CODE> 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,

</P>

<PRE class="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]
</PRE>

<P>
The values of the ranges are formatted using <VAR>range_format</VAR> and the
value of the bins are formatted using <VAR>bin_format</VAR>.  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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_fscanf</B> <I>(FILE * <VAR>stream</VAR>, gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1764"></A>
This function reads formatted data from the stream <VAR>stream</VAR> into the
histogram <VAR>h</VAR>.  The data is assumed to be in the three-column format
used by <CODE>gsl_histogram_fprintf</CODE>.  The histogram <VAR>h</VAR> must be
preallocated with the correct length since the function uses the size of
<VAR>h</VAR> to determine how many numbers to read.  The function returns 0
for success and <CODE>GSL_EFAILED</CODE> if there was a problem reading from
the file.
</DL>

</P>


<H2><A NAME="SEC347" HREF="gsl-ref_toc.html#TOC347">Resampling from histograms</A></H2>
<P>
<A NAME="IDX1765"></A>
<A NAME="IDX1766"></A>
<A NAME="IDX1767"></A>

</P>
<P>
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
x falls in the range of that bin.  The probability distribution
function has the one-dimensional form p(x)dx where,

</P>

<PRE class="example">
p(x) = n_i/ (N w_i)
</PRE>

<P>
In this equation n_i is the number of events in the bin which
contains x, w_i is the width of the bin and N is
the total number of events.  The distribution of events within each bin
is assumed to be uniform.

</P>


<H2><A NAME="SEC348" HREF="gsl-ref_toc.html#TOC348">The histogram probability distribution struct</A></H2>
<P>
<A NAME="IDX1768"></A>
<A NAME="IDX1769"></A>
<A NAME="IDX1770"></A>
<A NAME="IDX1771"></A>
The probability distribution function for a histogram consists of a set
of <I>bins</I> which measure the probability of an event falling into a
given range of a continuous variable 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.

</P>
<P>
<DL>
<DT><U>Data Type:</U> <B>gsl_histogram_pdf</B>
<DD><A NAME="IDX1772"></A>
<DL COMPACT>

<DT><CODE>size_t n</CODE>
<DD>
This is the number of bins used to approximate the probability
distribution function. 
<DT><CODE>double * range</CODE>
<DD>
The ranges of the bins are stored in an array of <VAR>n+1</VAR> elements
pointed to by <VAR>range</VAR>.
<DT><CODE>double * sum</CODE>
<DD>
The cumulative probability for the bins is stored in an array of
<VAR>n</VAR> elements pointed to by <VAR>sum</VAR>.
</DL>
</DL>
<P>
The following functions allow you to create a <CODE>gsl_histogram_pdf</CODE>
struct which represents this probability distribution and generate
random samples from it.

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_histogram_pdf * <B>gsl_histogram_pdf_alloc</B> <I>(size_t <VAR>n</VAR>)</I>
<DD><A NAME="IDX1773"></A>
This function allocates memory for a probability distribution with
<VAR>n</VAR> bins and returns a pointer to a newly initialized
<CODE>gsl_histogram_pdf</CODE> 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</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram_pdf_init</B> <I>(gsl_histogram_pdf * <VAR>p</VAR>, const gsl_histogram * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1774"></A>
This function initializes the probability distribution <VAR>p</VAR> with
the contents of the histogram <VAR>h</VAR>. If any of the bins of <VAR>h</VAR> are
negative then the error handler is invoked with an error code of
<CODE>GSL_EDOM</CODE> because a probability distribution cannot contain
negative values.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram_pdf_free</B> <I>(gsl_histogram_pdf * <VAR>p</VAR>)</I>
<DD><A NAME="IDX1775"></A>
This function frees the probability distribution function <VAR>p</VAR> and
all of the memory associated with it.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram_pdf_sample</B> <I>(const gsl_histogram_pdf * <VAR>p</VAR>, double <VAR>r</VAR>)</I>
<DD><A NAME="IDX1776"></A>
This function uses <VAR>r</VAR>, a uniform random number between zero and
one, to compute a single random sample from the probability distribution
<VAR>p</VAR>.  The algorithm used to compute the sample s is given by
the following formula,

</P>

<PRE class="example">
s = range[i] + delta * (range[i+1] - range[i])
</PRE>

<P>
where i is the index which satisfies 
sum[i] &#60;=  r &#60; sum[i+1] and 
delta is 
(r - sum[i])/(sum[i+1] - sum[i]).
</DL>

</P>


<H2><A NAME="SEC349" HREF="gsl-ref_toc.html#TOC349">Example programs for histograms</A></H2>

<P>
The following program shows how to make a simple histogram of a column
of numerical data supplied on <CODE>stdin</CODE>.  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</CODE>, 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</CODE>.

</P>

<PRE class="example">
#include &#60;stdio.h&#62;
#include &#60;stdlib.h&#62;
#include &#60;gsl/gsl_histogram.h&#62;

int
main (int argc, char **argv)
{
  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]);

  {
    double x;

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

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

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

    gsl_histogram_free (h);
  }
  
  exit (0);
}
</PRE>

<P>
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.

</P>

<PRE class="example">
$ gsl-randist 0 10000 cauchy 30 
   | gsl-histogram -100 100 200 &#62; histogram.dat
</PRE>

<P>
A plot of the resulting histogram shows the familiar shape of the
Cauchy distribution and the fluctuations caused by the finite sample
size.

</P>

<PRE class="example">
$ awk '{print $1, $3 ; print $2, $3}' histogram.dat 
   | graph -T X
</PRE>



<H2><A NAME="SEC350" HREF="gsl-ref_toc.html#TOC350">Two dimensional histograms</A></H2>
<P>
<A NAME="IDX1777"></A>
<A NAME="IDX1778"></A>

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

</P>


<H2><A NAME="SEC351" HREF="gsl-ref_toc.html#TOC351">The 2D histogram struct</A></H2>

<P>
Two dimensional histograms are defined by the following struct,

</P>
<P>
<DL>
<DT><U>Data Type:</U> <B>gsl_histogram2d</B>
<DD><A NAME="IDX1779"></A>
<DL COMPACT>

<DT><CODE>size_t nx, ny</CODE>
<DD>
This is the number of histogram bins in the x and y directions.
<DT><CODE>double * xrange</CODE>
<DD>
The ranges of the bins in the x-direction are stored in an array of
<VAR>nx + 1</VAR> elements pointed to by <VAR>xrange</VAR>.
<DT><CODE>double * yrange</CODE>
<DD>
The ranges of the bins in the y-direction are stored in an array of
<VAR>ny + 1</VAR> pointed to by <VAR>yrange</VAR>.
<DT><CODE>double * bin</CODE>
<DD>
The counts for each bin are stored in an array pointed to by <VAR>bin</VAR>.
The bins are floating-point numbers, so you can increment them by
non-integer values if necessary.  The array <VAR>bin</VAR> stores the two
dimensional array of bins in a single block of memory according to the
mapping <CODE>bin(i,j)</CODE> = <CODE>bin[i * ny + j]</CODE>.
</DL>
</DL>
<P>
The range for <CODE>bin(i,j)</CODE> is given by <CODE>xrange[i]</CODE> to
<CODE>xrange[i+1]</CODE> in the x-direction and <CODE>yrange[j]</CODE> to
<CODE>yrange[j+1]</CODE> 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,

</P>

<PRE class="display">
bin(i,j) corresponds to xrange[i] &#60;= x &#60; xrange[i+1]
                    and yrange[j] &#60;= y &#60; yrange[j+1]
</PRE>

<P>
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.

</P>
<P>
The <CODE>gsl_histogram2d</CODE> struct and its associated functions are
defined in the header file <TT>'gsl_histogram2d.h'</TT>.

</P>


<H2><A NAME="SEC352" HREF="gsl-ref_toc.html#TOC352">2D Histogram allocation</A></H2>

<P>
The functions for allocating memory to a 2D histogram follow the style
of <CODE>malloc</CODE> and <CODE>free</CODE>.  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</CODE>) 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</CODE>.

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_histogram2d * <B>gsl_histogram2d_alloc</B> <I>(size_t <VAR>nx</VAR>, size_t <VAR>ny</VAR>)</I>
<DD><A NAME="IDX1780"></A>
This function allocates memory for a two-dimensional histogram with
<VAR>nx</VAR> bins in the x direction and <VAR>ny</VAR> bins in the y direction.
The function returns a pointer to a newly created <CODE>gsl_histogram2d</CODE>
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</CODE>. The bins and ranges must be initialized with one of
the functions below before the histogram is ready for use.
</DL>

</P>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_set_ranges</B> <I>(gsl_histogram2d * <VAR>h</VAR>, const double <VAR>xrange</VAR>[], size_t <VAR>xsize</VAR>, const double <VAR>yrange</VAR>[], size_t <VAR>ysize</VAR>)</I>
<DD><A NAME="IDX1781"></A>
This function sets the ranges of the existing histogram <VAR>h</VAR> using
the arrays <VAR>xrange</VAR> and <VAR>yrange</VAR> of size <VAR>xsize</VAR> and
<VAR>ysize</VAR> respectively.  The values of the histogram bins are reset to
zero.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_set_ranges_uniform</B> <I>(gsl_histogram2d * <VAR>h</VAR>, double <VAR>xmin</VAR>, double <VAR>xmax</VAR>, double <VAR>ymin</VAR>, double <VAR>ymax</VAR>)</I>
<DD><A NAME="IDX1782"></A>
This function sets the ranges of the existing histogram <VAR>h</VAR> to cover
the ranges <VAR>xmin</VAR> to <VAR>xmax</VAR> and <VAR>ymin</VAR> to <VAR>ymax</VAR>
uniformly.  The values of the histogram bins are reset to zero.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram2d_free</B> <I>(gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1783"></A>
This function frees the 2D histogram <VAR>h</VAR> and all of the memory
associated with it.
</DL>

</P>


<H2><A NAME="SEC353" HREF="gsl-ref_toc.html#TOC353">Copying 2D Histograms</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_memcpy</B> <I>(gsl_histogram2d * <VAR>dest</VAR>, const gsl_histogram2d * <VAR>src</VAR>)</I>
<DD><A NAME="IDX1784"></A>
This function copies the histogram <VAR>src</VAR> into the pre-existing
histogram <VAR>dest</VAR>, making <VAR>dest</VAR> into an exact copy of <VAR>src</VAR>.
The two histograms must be of the same size.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_histogram2d * <B>gsl_histogram2d_clone</B> <I>(const gsl_histogram2d * <VAR>src</VAR>)</I>
<DD><A NAME="IDX1785"></A>
This function returns a pointer to a newly created histogram which is an
exact copy of the histogram <VAR>src</VAR>.
</DL>

</P>


<H2><A NAME="SEC354" HREF="gsl-ref_toc.html#TOC354">Updating and accessing 2D histogram elements</A></H2>

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

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_increment</B> <I>(gsl_histogram2d * <VAR>h</VAR>, double <VAR>x</VAR>, double <VAR>y</VAR>)</I>
<DD><A NAME="IDX1786"></A>
This function updates the histogram <VAR>h</VAR> by adding one (1.0) to the
bin whose x and y ranges contain the coordinates (<VAR>x</VAR>,<VAR>y</VAR>).

</P>
<P>
If the point (x,y) lies inside the valid ranges of the
histogram then the function returns zero to indicate success.  If
(x,y) lies outside the limits of the histogram then the
function returns <CODE>GSL_EDOM</CODE>, 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_accumulate</B> <I>(gsl_histogram2d * <VAR>h</VAR>, double <VAR>x</VAR>, double <VAR>y</VAR>, double <VAR>weight</VAR>)</I>
<DD><A NAME="IDX1787"></A>
This function is similar to <CODE>gsl_histogram2d_increment</CODE> but increases
the value of the appropriate bin in the histogram <VAR>h</VAR> by the
floating-point number <VAR>weight</VAR>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_get</B> <I>(const gsl_histogram2d * <VAR>h</VAR>, size_t <VAR>i</VAR>, size_t <VAR>j</VAR>)</I>
<DD><A NAME="IDX1788"></A>
This function returns the contents of the (<VAR>i</VAR>,<VAR>j</VAR>)th bin of the
histogram <VAR>h</VAR>.  If (<VAR>i</VAR>,<VAR>j</VAR>) lies outside the valid range of
indices for the histogram then the error handler is called with an error
code of <CODE>GSL_EDOM</CODE> and the function returns 0.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_get_xrange</B> <I>(const gsl_histogram2d * <VAR>h</VAR>, size_t <VAR>i</VAR>, double * <VAR>xlower</VAR>, double * <VAR>xupper</VAR>)</I>
<DD><A NAME="IDX1789"></A>
<DT><U>Function:</U> int <B>gsl_histogram2d_get_yrange</B> <I>(const gsl_histogram2d * <VAR>h</VAR>, size_t <VAR>j</VAR>, double * <VAR>ylower</VAR>, double * <VAR>yupper</VAR>)</I>
<DD><A NAME="IDX1790"></A>
These functions find the upper and lower range limits of the <VAR>i</VAR>-th
and <VAR>j</VAR>-th bins in the x and y directions of the histogram <VAR>h</VAR>.
The range limits are stored in <VAR>xlower</VAR> and <VAR>xupper</VAR> or
<VAR>ylower</VAR> and <VAR>yupper</VAR>.  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</VAR> or
<VAR>j</VAR> lies outside the valid range of indices for the histogram then
the error handler is called with an error code of <CODE>GSL_EDOM</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_xmax</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1791"></A>
<DT><U>Function:</U> double <B>gsl_histogram2d_xmin</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1792"></A>
<DT><U>Function:</U> size_t <B>gsl_histogram2d_nx</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1793"></A>
<DT><U>Function:</U> double <B>gsl_histogram2d_ymax</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1794"></A>
<DT><U>Function:</U> double <B>gsl_histogram2d_ymin</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1795"></A>
<DT><U>Function:</U> size_t <B>gsl_histogram2d_ny</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1796"></A>
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</VAR>.  They provide a way of determining these values without
accessing the <CODE>gsl_histogram2d</CODE> struct directly.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram2d_reset</B> <I>(gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1797"></A>
This function resets all the bins of the histogram <VAR>h</VAR> to zero.
</DL>

</P>


<H2><A NAME="SEC355" HREF="gsl-ref_toc.html#TOC355">Searching 2D histogram ranges</A></H2>

<P>
The following functions are used by the access and update routines to
locate the bin which corresponds to a given (x,y) coordinate.

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_find</B> <I>(const gsl_histogram2d * <VAR>h</VAR>, double <VAR>x</VAR>, double <VAR>y</VAR>, size_t * <VAR>i</VAR>, size_t * <VAR>j</VAR>)</I>
<DD><A NAME="IDX1798"></A>
This function finds and sets the indices <VAR>i</VAR> and <VAR>j</VAR> to the to
the bin which covers the coordinates (<VAR>x</VAR>,<VAR>y</VAR>). 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 (x,y) is found then the function sets the
indices (<VAR>i</VAR>,<VAR>j</VAR>) and returns <CODE>GSL_SUCCESS</CODE>.  If
(x,y) lies outside the valid range of the histogram then the
function returns <CODE>GSL_EDOM</CODE> and the error handler is invoked.
</DL>

</P>


<H2><A NAME="SEC356" HREF="gsl-ref_toc.html#TOC356">2D Histogram Statistics</A></H2>

<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_max_val</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1799"></A>
This function returns the maximum value contained in the histogram bins.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram2d_max_bin</B> <I>(const gsl_histogram2d * <VAR>h</VAR>, size_t * <VAR>i</VAR>, size_t * <VAR>j</VAR>)</I>
<DD><A NAME="IDX1800"></A>
This function returns the indices (<VAR>i</VAR>,<VAR>j</VAR>) of the bin
containing the maximum value in the histogram <VAR>h</VAR>. In the case where
several bins contain the same maximum value the first bin found is
returned.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_min_val</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1801"></A>
This function returns the minimum value contained in the histogram bins.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram2d_min_bin</B> <I>(const gsl_histogram2d * <VAR>h</VAR>, size_t * <VAR>i</VAR>, size_t * <VAR>j</VAR>)</I>
<DD><A NAME="IDX1802"></A>
This function returns the indices (<VAR>i</VAR>,<VAR>j</VAR>) of the bin
containing the minimum value in the histogram <VAR>h</VAR>. In the case where
several bins contain the same maximum value the first bin found is
returned.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_xmean</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1803"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_ymean</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1804"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_xsigma</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1805"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_ysigma</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1806"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_cov</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1807"></A>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> double <B>gsl_histogram2d_sum</B> <I>(const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1808"></A>
This function returns the sum of all bin values. Negative bin values
are included in the sum.
</DL>

</P>


<H2><A NAME="SEC357" HREF="gsl-ref_toc.html#TOC357">2D Histogram Operations</A></H2>

<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_equal_bins_p</B> <I>(const gsl_histogram2d *<VAR>h1</VAR>, const gsl_histogram2d *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1809"></A>
This function returns 1 if the all of the individual bin ranges of the
two histograms are identical, and 0 otherwise.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_add</B> <I>(gsl_histogram2d *<VAR>h1</VAR>, const gsl_histogram2d *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1810"></A>
This function adds the contents of the bins in histogram <VAR>h2</VAR> to the
corresponding bins of histogram <VAR>h1</VAR>,
i.e. h'_1(i,j) = h_1(i,j) + h_2(i,j).
The two histograms must have identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_sub</B> <I>(gsl_histogram2d *<VAR>h1</VAR>, const gsl_histogram2d *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1811"></A>
This function subtracts the contents of the bins in histogram <VAR>h2</VAR> from the
corresponding bins of histogram <VAR>h1</VAR>,
i.e. h'_1(i,j) = h_1(i,j) - h_2(i,j).
The two histograms must have identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_mul</B> <I>(gsl_histogram2d *<VAR>h1</VAR>, const gsl_histogram2d *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1812"></A>
This function multiplies the contents of the bins of histogram <VAR>h1</VAR>
by the contents of the corresponding bins in histogram <VAR>h2</VAR>,
i.e. h'_1(i,j) = h_1(i,j) * h_2(i,j).
The two histograms must have identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_div</B> <I>(gsl_histogram2d *<VAR>h1</VAR>, const gsl_histogram2d *<VAR>h2</VAR>)</I>
<DD><A NAME="IDX1813"></A>
This function divides the contents of the bins of histogram <VAR>h1</VAR>
by the contents of the corresponding bins in histogram <VAR>h2</VAR>,
i.e. h'_1(i,j) = h_1(i,j) / h_2(i,j).
The two histograms must have identical bin ranges.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_scale</B> <I>(gsl_histogram2d *<VAR>h</VAR>, double <VAR>scale</VAR>)</I>
<DD><A NAME="IDX1814"></A>
This function multiplies the contents of the bins of histogram <VAR>h</VAR>
by the constant <VAR>scale</VAR>, i.e. 
h'_1(i,j) = h_1(i,j) scale.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_shift</B> <I>(gsl_histogram2d *<VAR>h</VAR>, double <VAR>offset</VAR>)</I>
<DD><A NAME="IDX1815"></A>
This function shifts the contents of the bins of histogram <VAR>h</VAR>
by the constant <VAR>offset</VAR>, i.e. 
h'_1(i,j) = h_1(i,j) + offset.
</DL>

</P>


<H2><A NAME="SEC358" HREF="gsl-ref_toc.html#TOC358">Reading and writing 2D histograms</A></H2>

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

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_fwrite</B> <I>(FILE * <VAR>stream</VAR>, const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1816"></A>
This function writes the ranges and bins of the histogram <VAR>h</VAR> to the
stream <VAR>stream</VAR> in binary format.  The return value is 0 for success
and <CODE>GSL_EFAILED</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_fread</B> <I>(FILE * <VAR>stream</VAR>, gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1817"></A>
This function reads into the histogram <VAR>h</VAR> from the stream
<VAR>stream</VAR> in binary format.  The histogram <VAR>h</VAR> must be
preallocated with the correct size since the function uses the number of
x and y bins in <VAR>h</VAR> to determine how many bytes to read.  The return
value is 0 for success and <CODE>GSL_EFAILED</CODE> 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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_fprintf</B> <I>(FILE * <VAR>stream</VAR>, const gsl_histogram2d * <VAR>h</VAR>, const char * <VAR>range_format</VAR>, const char * <VAR>bin_format</VAR>)</I>
<DD><A NAME="IDX1818"></A>
This function writes the ranges and bins of the histogram <VAR>h</VAR>
line-by-line to the stream <VAR>stream</VAR> using the format specifiers
<VAR>range_format</VAR> and <VAR>bin_format</VAR>.  These should be one of the
<CODE>%g</CODE>, <CODE>%e</CODE> or <CODE>%f</CODE> formats for floating point
numbers.  The function returns 0 for success and <CODE>GSL_EFAILED</CODE> 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,

</P>

<PRE class="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)
</PRE>

<P>
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.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_fscanf</B> <I>(FILE * <VAR>stream</VAR>, gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1819"></A>
This function reads formatted data from the stream <VAR>stream</VAR> into the
histogram <VAR>h</VAR>.  The data is assumed to be in the five-column format
used by <CODE>gsl_histogram_fprintf</CODE>.  The histogram <VAR>h</VAR> must be
preallocated with the correct lengths since the function uses the sizes
of <VAR>h</VAR> to determine how many numbers to read.  The function returns 0
for success and <CODE>GSL_EFAILED</CODE> if there was a problem reading from
the file.
</DL>

</P>


<H2><A NAME="SEC359" HREF="gsl-ref_toc.html#TOC359">Resampling from 2D histograms</A></H2>

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

</P>

<PRE class="example">
p(x,y) = n_{ij}/ (N A_{ij})
</PRE>

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

</P>
<P>
<DL>
<DT><U>Data Type:</U> <B>gsl_histogram2d_pdf</B>
<DD><A NAME="IDX1820"></A>
<DL COMPACT>

<DT><CODE>size_t nx, ny</CODE>
<DD>
This is the number of histogram bins used to approximate the probability
distribution function in the x and y directions.
<DT><CODE>double * xrange</CODE>
<DD>
The ranges of the bins in the x-direction are stored in an array of
<VAR>nx + 1</VAR> elements pointed to by <VAR>xrange</VAR>.
<DT><CODE>double * yrange</CODE>
<DD>
The ranges of the bins in the y-direction are stored in an array of
<VAR>ny + 1</VAR> pointed to by <VAR>yrange</VAR>.
<DT><CODE>double * sum</CODE>
<DD>
The cumulative probability for the bins is stored in an array of
<VAR>nx</VAR>*<VAR>ny</VAR> elements pointed to by <VAR>sum</VAR>.
</DL>
</DL>
<P>
The following functions allow you to create a <CODE>gsl_histogram2d_pdf</CODE>
struct which represents a two dimensional probability distribution and
generate random samples from it.

</P>
<P>
<DL>
<DT><U>Function:</U> gsl_histogram2d_pdf * <B>gsl_histogram2d_pdf_alloc</B> <I>(size_t <VAR>nx</VAR>, size_t <VAR>ny</VAR>)</I>
<DD><A NAME="IDX1821"></A>
This function allocates memory for a two-dimensional probability
distribution of size <VAR>nx</VAR>-by-<VAR>ny</VAR> and returns a pointer to a
newly initialized <CODE>gsl_histogram2d_pdf</CODE> 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</CODE>.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_pdf_init</B> <I>(gsl_histogram2d_pdf * <VAR>p</VAR>, const gsl_histogram2d * <VAR>h</VAR>)</I>
<DD><A NAME="IDX1822"></A>
This function initializes the two-dimensional probability distribution
calculated <VAR>p</VAR> from the histogram <VAR>h</VAR>.  If any of the bins of
<VAR>h</VAR> are negative then the error handler is invoked with an error
code of <CODE>GSL_EDOM</CODE> because a probability distribution cannot
contain negative values.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> void <B>gsl_histogram2d_pdf_free</B> <I>(gsl_histogram2d_pdf * <VAR>p</VAR>)</I>
<DD><A NAME="IDX1823"></A>
This function frees the two-dimensional probability distribution
function <VAR>p</VAR> and all of the memory associated with it.
</DL>

</P>
<P>
<DL>
<DT><U>Function:</U> int <B>gsl_histogram2d_pdf_sample</B> <I>(const gsl_histogram2d_pdf * <VAR>p</VAR>, double <VAR>r1</VAR>, double <VAR>r2</VAR>, double * <VAR>x</VAR>, double * <VAR>y</VAR>)</I>
<DD><A NAME="IDX1824"></A>
This function uses two uniform random numbers between zero and one,
<VAR>r1</VAR> and <VAR>r2</VAR>, to compute a single random sample from the
two-dimensional probability distribution <VAR>p</VAR>.
</DL>

</P>


<H2><A NAME="SEC360" HREF="gsl-ref_toc.html#TOC360">Example programs for 2D histograms</A></H2>
<P>
This program demonstrates two features of two-dimensional histograms.
First a 10-by-10 two-dimensional 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.

</P>

<PRE class="example">
#include &#60;stdio.h&#62;
#include &#60;gsl/gsl_rng.h&#62;
#include &#60;gsl/gsl_histogram2d.h&#62;

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-&#62;nx, h-&#62;ny);
    
    gsl_histogram2d_pdf_init (p, h);

    for (i = 0; i &#60; 1000; i++) {
      double x, y;
      double u = gsl_rng_uniform (r);
      double v = gsl_rng_uniform (r);
       
      gsl_histogram2d_pdf_sample (p, u, v, &#38;x, &#38;y);
      
      printf ("%g %g\n", x, y);
    }
  }
  
 return 0;
}
</PRE>

<P>
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.

</P>

<P><HR><P>
<p>Go to the <A HREF="gsl-ref_1.html">first</A>, <A HREF="gsl-ref_20.html">previous</A>, <A HREF="gsl-ref_22.html">next</A>, <A HREF="gsl-ref_50.html">last</A> section, <A HREF="gsl-ref_toc.html">table of contents</A>.
</BODY>
</HTML>