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