1%perlcode %{
2@EXPORT_OK = qw/
3               gsl_histogram2d_alloc
4               gsl_histogram2d_calloc
5               gsl_histogram2d_calloc_uniform
6               gsl_histogram2d_free
7               gsl_histogram2d_increment
8               gsl_histogram2d_accumulate
9               gsl_histogram2d_find
10               gsl_histogram2d_get
11               gsl_histogram2d_get_xrange
12               gsl_histogram2d_get_yrange
13               gsl_histogram2d_xmax
14               gsl_histogram2d_xmin
15               gsl_histogram2d_nx
16               gsl_histogram2d_ymax
17               gsl_histogram2d_ymin
18               gsl_histogram2d_ny
19               gsl_histogram2d_reset
20               gsl_histogram2d_calloc_range
21               gsl_histogram2d_set_ranges_uniform
22               gsl_histogram2d_set_ranges
23               gsl_histogram2d_memcpy
24               gsl_histogram2d_clone
25               gsl_histogram2d_max_val
26               gsl_histogram2d_max_bin
27               gsl_histogram2d_min_val
28               gsl_histogram2d_min_bin
29               gsl_histogram2d_xmean
30               gsl_histogram2d_ymean
31               gsl_histogram2d_xsigma
32               gsl_histogram2d_ysigma
33               gsl_histogram2d_cov
34               gsl_histogram2d_sum
35               gsl_histogram2d_equal_bins_p
36               gsl_histogram2d_add
37               gsl_histogram2d_sub
38               gsl_histogram2d_mul
39               gsl_histogram2d_div
40               gsl_histogram2d_scale
41               gsl_histogram2d_shift
42               gsl_histogram2d_fwrite
43               gsl_histogram2d_fread
44               gsl_histogram2d_fprintf
45               gsl_histogram2d_fscanf
46               gsl_histogram2d_pdf_alloc
47               gsl_histogram2d_pdf_init
48               gsl_histogram2d_pdf_free
49               gsl_histogram2d_pdf_sample
50             /;
51%EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
52
53=encoding utf8
54
55=head1 NAME
56
57Math::GSL::Histogram2D - Create and manipulate histograms of data in 2 dimensions
58
59=head1 SYNOPSIS
60
61    use Math::GSL::Histogram2D qw/:all/;
62
63    # raw interface
64    my $H = gsl_histogram2d_alloc(100, 100);
65
66    gsl_histogram2d_set_ranges_uniform($H,0,101, 0, 101);
67    gsl_histogram2d_increment($H, -50, -12);  # ignored
68    gsl_histogram2d_increment($H, 70 );
69    gsl_histogram2d_increment($H, 85.2 );
70
71    my $G          = gsl_histogram2d_clone($H);
72    my $value      = gsl_histogram2d_get($G, 70, 33);
73    my ($max,$min) = (gsl_histogram2d_min_val($H), gsl_histogram2d_max_val($H) );
74    my $sum        = gsl_histogram2d_sum($H);
75
76=cut
77
78=head1 DESCRIPTION
79
80This subsystem allows the creation and manipulation of 2D histograms. Currently, only a raw interface exists.
81
82=over
83
84=item C<gsl_histogram2d_alloc($nx, $ny)> - This function allocates memory for a two-dimensional histogram with $nx bins in the x direction and $ny bins in the y direction. The function returns a pointer to a newly created gsl_histogram2d struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code of $GSL_ENOMEM. The bins and ranges must be initialized with one of the functions below before the histogram is ready for use.
85
86=item C<gsl_histogram2d_calloc >
87
88=item C<gsl_histogram2d_calloc_uniform >
89
90=item C<gsl_histogram2d_free($h)> - This function frees the 2D histogram h and all of the memory associated with it.
91
92=item C<gsl_histogram2d_increment($h, $xmin, $xmax, $ymin, $ymax)> - This function sets the ranges of the existing histogram $h to cover the ranges $xmin to $xmax and $ymin to $ymax uniformly. The values of the histogram bins are reset to zero.
93
94=item C<gsl_histogram2d_accumulate($h, $x, $y, $weight)> - This function is similar to gsl_histogram2d_increment but increases the value of the appropriate bin in the histogram $h by the floating-point number $weight.
95
96=item C<gsl_histogram2d_find($h, $x, $y)> - This function finds indices i and j to the 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 ($x,$y) is found then the function return GSL_SUCCESS, i and j in this order. If ($x,$y) lies outside the valid range of the histogram then the function returns $GSL_EDOM and the error handler is invoked.
97
98=item C<gsl_histogram2d_get($h, $i, $j)> - This function returns the contents of the ($i,$j)-th bin of the histogram $h. If ($i,$j) lies outside the valid range of indices for the histogram then the error handler is called with an error code of $GSL_EDOM and the function returns 0.
99
100=item C<gsl_histogram2d_get_xrange($h, $i)> - This functions finds the upper and lower range limits of the $i-th in the x direction of the histogram $h. The range limits are stored in returned after 0 or 1 in this order : xlower and xupper. 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 returns 0 has first value to indicate success. If $i lies outside the valid range of indices for the histogram then the error handler is called with an error code of GSL_EDOM.
101
102=item C<gsl_histogram2d_get_yrange($h, $j)> - This functions finds the upper and lower range limits of the $j-th in the y direction of the histogram $h. The range limits are stored in returned after 0 or 1 in this order : ylower and yupper. The lower limits are inclusive (i.e. events with these coordinates are included in the bin) and the upper limits are exclusive (i.e. events with the value of the upper limit are not included and fall in the neighboring higher bin, if it exists). The functions returns 0 has first value to indicate success. If $j lies outside the valid range of indices for the histogram then the error handler is called with an error code of GSL_EDOM.
103
104=item C<gsl_histogram2d_xmax($h)> - This functions returns the maximum upper range limit for the x direction of the histogram $h.
105
106=item C<gsl_histogram2d_xmin($h)> - This functions returns the minimum lower range limit for the x direction of the histogram $h.
107
108=item C<gsl_histogram2d_nx($h)> - This functions the number of bins for the x direction.
109
110=item C<gsl_histogram2d_ymax($h)> - This functions returns the maximum upper range limit for the y direction of the histogram $h.
111
112=item C<gsl_histogram2d_ymin($h)> - This functions returns the minimum lower range limit for the y direction of the histogram $h.
113
114=item C<gsl_histogram2d_ny($h)> - This functions the number of bins for the y direction.
115
116=item C<gsl_histogram2d_reset($h)> - This function resets all the bins of the histogram $h to zero.
117
118=item C<gsl_histogram2d_calloc_range >
119
120=item C<gsl_histogram2d_set_ranges($h, $xrange, $xsize, $yrange, $ysize)> - This function sets the ranges of the existing histogram $h using the arrays $xrange and $yrange of size $xsize and $ysize respectively. The values of the histogram bins are reset to zero.
121
122=item C<gsl_histogram2d_set_ranges_uniform($h, $xmin, $xmax, $ymin, $ymax)> - This function sets the ranges of the existing histogram $h to cover the ranges $xmin to $xmax and $ymin to $ymax uniformly. The values of the histogram bins are reset to zero.
123
124=item C<gsl_histogram2d_memcpy($dest, $src)> - This function copies the histogram $src into the pre-existing histogram $dest, making $dest into an exact copy of $src. The two histograms must be of the same size.
125
126
127=item C<gsl_histogram2d_clone($src)>
128
129This function returns a pointer to a newly created
130Math::GSL::Histogram2D::gsl_histogram2d which is an exact copy of the histogram
131$src. NOTE: Ranges must be set with a function like
132C<gsl_histogram2d_set_ranges_uniform> or this function will return undef.
133
134=item C<gsl_histogram2d_max_val($h)> - This function returns the maximum value contained in the histogram bins.
135
136=item C<gsl_histogram2d_max_bin($h)> - This function finds the indices of the bin containing the maximum value in the histogram $h and returns the result in this order : 0 if the operation succeded, 1 otherwise, i and j. In the case where several bins contain the same maximum value the first bin found is returned.
137
138=item C<gsl_histogram2d_min_val($h)> - This function returns the minimum value contained in the histogram bins.
139
140=item C<gsl_histogram2d_min_bin($h)> - This function finds the indices of the bin containing the minimum value in the histogram $h and returns the result in this order : 0 if the operation succeded, 1 otherwise, i and j. In the case where several bins contain the same minimum value the first bin found is returned.
141
142=item C<gsl_histogram2d_xmean($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.
143
144=item C<gsl_histogram2d_ymean($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.
145
146=item C<gsl_histogram2d_xsigma($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.
147
148=item C<gsl_histogram2d_ysigma($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.
149
150=item C<gsl_histogram2d_cov($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.
151
152=item C<gsl_histogram2d_sum($h)> - This function returns the sum of all bin values. Negative bin values are included in the sum.
153
154=item C<gsl_histogram2d_equal_bins_p($h1, $h2)> - This function returns 1 if all the individual bin ranges of the two histograms are identical, and 0 otherwise.
155
156=item C<gsl_histogram2d_add($h1, $h2)> - This function adds the contents of the bins in histogram $h2 to the corresponding bins of histogram $h1, i.e. h'_1(i,j) = h_1(i,j) + h_2(i,j). The two histograms must have identical bin ranges.
157
158=item C<gsl_histogram2d_sub($h1, $h2)> - This function subtracts the contents of the bins in histogram $h2 from the corresponding bins of histogram $h1, i.e. h'_1(i,j) = h_1(i,j) - h_2(i,j). The two histograms must have identical bin ranges.
159
160=item C<gsl_histogram2d_mul($h1, $h2)> - This function multiplies the contents of the bins of histogram $h1 by the contents of the corresponding bins in histogram $h2, i.e. h'_1(i,j) = h_1(i,j) * h_2(i,j). The two histograms must have identical bin ranges.
161
162=item C<gsl_histogram2d_div($h1, $h2)> - This function divides the contents of the bins of histogram $h1 by the contents of the corresponding bins in histogram $h2, i.e. h'_1(i,j) = h_1(i,j) / h_2(i,j). The two histograms must have identical bin ranges.
163
164=item C<gsl_histogram2d_scale($h, $scale)> - This function multiplies the contents of the bins of histogram $h by the constant scale, i.e. h'_1(i,j) = h_1(i,j) $scale.
165
166=item C<gsl_histogram2d_shift($h, $offset)> - This function shifts the contents of the bins of histogram $h by the constant offset, i.e. h'_1(i,j) = h_1(i,j) + $offset.
167
168=item C<gsl_histogram2d_fwrite($stream $h)> - This function writes the ranges and bins of the histogram $h to the stream $stream (opened with the gsl_fopen function from the Math::GSL module) in binary format. The return value is 0 for success and $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.
169
170=item C<gsl_histogram2d_fread($stream $h)> - This function reads into the histogram $h from the stream $stream (opened with the gsl_fopen function from the Math::GSL module) in binary format. The histogram $h must be preallocated with the correct size since the function uses the number of x and y bins in $h to determine how many bytes to read. The return value is 0 for success and $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.
171
172=item C<gsl_histogram2d_fprintf($stream, $h, $range_format, $bin_format)> - This function writes the ranges and bins of the histogram $h line-by-line to the stream $stream (opened with the gsl_fopen function from the Math::GSL module) using the format specifiers $range_format and $bin_format. These should be one of the %g, %e or %f formats for floating point numbers. The function returns 0 for success and $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,
173
174=over
175
176=item xrange[0] xrange[1] yrange[0] yrange[1] bin(0,0)
177
178=item xrange[0] xrange[1] yrange[1] yrange[2] bin(0,1)
179
180=item xrange[0] xrange[1] yrange[2] yrange[3] bin(0,2)
181
182=item ....
183
184=item xrange[0] xrange[1] yrange[ny-1] yrange[ny] bin(0,ny-1)
185
186=item xrange[1] xrange[2] yrange[0] yrange[1] bin(1,0)
187
188=item xrange[1] xrange[2] yrange[1] yrange[2] bin(1,1)
189
190=item xrange[1] xrange[2] yrange[1] yrange[2] bin(1,2)
191
192=item ....
193
194=item xrange[1] xrange[2] yrange[ny-1] yrange[ny] bin(1,ny-1)
195
196=item ....
197
198=item xrange[nx-1] xrange[nx] yrange[0] yrange[1] bin(nx-1,0)
199
200=item xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,1)
201
202=item xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,2)
203
204=item ....
205
206=item xrange[nx-1] xrange[nx] yrange[ny-1] yrange[ny] bin(nx-1,ny-1)
207
208=back
209
210Each line contains the lower and upper limits of the bin and the contents of the
211bin. Since the upper limits of the each bin are the lower limits of the
212neighboring bins there is duplication of these values but this allows the
213histogram to be manipulated with line-oriented tools.
214
215=item C<gsl_histogram2d_fscanf($stream, $h)>
216
217This function reads formatted data from the stream $stream (opened with the
218gsl_fopen function from the Math::GSL module) into the histogram $h. The data is
219assumed to be in the five-column format used by gsl_histogram2d_fprintf. The
220histogram $h must be preallocated with the correct lengths since the function
221uses the sizes of $h to determine how many numbers to read. The function returns
2220 for success and $GSL_EFAILED if there was a problem reading from the file.
223
224=item C<gsl_histogram2d_pdf_alloc($nx, $ny)>
225
226This function allocates memory for a two-dimensional probability distribution of
227size $nx-by-$ny and returns a pointer to a newly initialized gsl_histogram2d_pdf
228struct. If insufficient memory is available a null pointer is returned and the
229error handler is invoked with an error code of $GSL_ENOMEM.
230
231=item C<gsl_histogram2d_pdf_init($p, $h)>
232
233This function initializes the two-dimensional probability distribution
234calculated $p from the histogram $h. If any of the bins of $h are negative then
235the error handler is invoked with an error code of GSL_EDOM because a
236probability distribution cannot contain negative values.
237
238=item C<gsl_histogram2d_pdf_free($p)>
239
240This function frees the two-dimensional probability distribution function $p and
241all of the memory associated with it.
242
243=item C<gsl_histogram2d_pdf_sample($p, $r1, $r2)>
244
245This function uses two uniform random numbers between zero and one, $r1 and $r2,
246to compute a single random sample from the two-dimensional probability
247distribution p. The function returns 0 if the operation succeeded, 1 otherwise
248followed by the x and y values of the sample.
249
250=back
251
252=head1 AUTHORS
253
254Jonathan "Duke" Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
255
256=head1 COPYRIGHT AND LICENSE
257
258Copyright (C) 2008-2021 Jonathan "Duke" Leto and Thierry Moisan
259
260This program is free software; you can redistribute it and/or modify it
261under the same terms as Perl itself.
262
263=cut
264
265%}
266