Histogram2D.i

   1 %module "Math::GSL::Histogram2D"
   2 %include "typemaps.i"
   3 %include "gsl_typemaps.i"
   4
   5 %apply double *OUTPUT { double * xlower, double * xupper, double * ylower, double * yupper, double * x, double * y};
   6 %apply int *OUTPUT { size_t * i, size_t * j };
   7
   8 FILE * fopen(char *, char *);
   9 int fclose(FILE *);
  10
  11 %{
  12     #include "gsl/gsl_histogram2d.h"
  13 %}
  14
  15 %include "gsl/gsl_histogram2d.h"
  16
  17
  18 %perlcode %{
  19 @EXPORT_OK = qw/fopen fclose
  20                gsl_histogram2d_alloc
  21                gsl_histogram2d_calloc
  22                gsl_histogram2d_calloc_uniform
  23                gsl_histogram2d_free
  24                gsl_histogram2d_increment
  25                gsl_histogram2d_accumulate
  26                gsl_histogram2d_find
  27                gsl_histogram2d_get
  28                gsl_histogram2d_get_xrange
  29                gsl_histogram2d_get_yrange
  30                gsl_histogram2d_xmax
  31                gsl_histogram2d_xmin
  32                gsl_histogram2d_nx
  33                gsl_histogram2d_ymax
  34                gsl_histogram2d_ymin
  35                gsl_histogram2d_ny
  36                gsl_histogram2d_reset
  37                gsl_histogram2d_calloc_range
  38                gsl_histogram2d_set_ranges_uniform
  39                gsl_histogram2d_set_ranges
  40                gsl_histogram2d_memcpy
  41                gsl_histogram2d_clone
  42                gsl_histogram2d_max_val
  43                gsl_histogram2d_max_bin
  44                gsl_histogram2d_min_val
  45                gsl_histogram2d_min_bin
  46                gsl_histogram2d_xmean
  47                gsl_histogram2d_ymean
  48                gsl_histogram2d_xsigma
  49                gsl_histogram2d_ysigma
  50                gsl_histogram2d_cov
  51                gsl_histogram2d_sum
  52                gsl_histogram2d_equal_bins_p
  53                gsl_histogram2d_add
  54                gsl_histogram2d_sub
  55                gsl_histogram2d_mul
  56                gsl_histogram2d_div
  57                gsl_histogram2d_scale
  58                gsl_histogram2d_shift
  59                gsl_histogram2d_fwrite
  60                gsl_histogram2d_fread
  61                gsl_histogram2d_fprintf
  62                gsl_histogram2d_fscanf
  63                gsl_histogram2d_pdf_alloc
  64                gsl_histogram2d_pdf_init
  65                gsl_histogram2d_pdf_free
  66                gsl_histogram2d_pdf_sample
  67              /;
  68 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
  69
  70 =head1 NAME
  71
  72 Math::GSL::Histogram2D - Create and manipulate histograms of data in 2 dimensions
  73
  74 =head1 SYNOPSIS
  75
  76     use Math::GSL::Histogram2D qw/:all/;
  77
  78     my $H = gsl_histogram2d_alloc(100, 100);
  79     gsl_histogram2d_set_ranges_uniform($H,0,101, 0, 101);
  80     gsl_histogram2d_increment($H, -50, -12);  # ignored
  81     gsl_histogram2d_increment($H, 70 );
  82     gsl_histogram2d_increment($H, 85.2 );
  83
  84     my $G = gsl_histogram2d_clone($H);
  85     my $value = gsl_histogram2d_get($G, 70, 33);
  86     my ($max,$min) = (gsl_histogram2d_min_val($H), gsl_histogram2d_max_val($H) );
  87     my $sum = gsl_histogram2d_sum($H);
  88
  89 =cut
  90
  91 =head1 DESCRIPTION
  92
  93 Here is a list of all the functions included in this module :
  94
  95 =over
  96
  97 =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.
  98
  99 =item C<gsl_histogram2d_calloc >
 100
 101 =item C<gsl_histogram2d_calloc_uniform >
 102
 103 =item C<gsl_histogram2d_free($h)> - This function frees the 2D histogram h and all of the memory associated with it.
 104
 105 =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.
 106
 107 =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.
 108
 109 =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.
 110
 111 =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.
 112
 113 =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.
 114
 115 =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.
 116
 117 =item C<gsl_histogram2d_xmax($h)> - This functions returns the maximum upper range limit for the x direction of the histogram $h.
 118
 119 =item C<gsl_histogram2d_xmin($h)> - This functions returns the minimum lower range limit for the x direction of the histogram $h.
 120
 121 =item C<gsl_histogram2d_nx($h)> - This functions the number of bins for the x direction.
 122
 123 =item C<gsl_histogram2d_ymax($h)> - This functions returns the maximum upper range limit for the y direction of the histogram $h.
 124
 125 =item C<gsl_histogram2d_ymin($h)> - This functions returns the minimum lower range limit for the y direction of the histogram $h.
 126
 127 =item C<gsl_histogram2d_ny($h)> - This functions the number of bins for the y direction.
 128
 129 =item C<gsl_histogram2d_reset($h)> - This function resets all the bins of the histogram $h to zero.
 130
 131 =item C<gsl_histogram2d_calloc_range >
 132
 133 =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.
 134
 135 =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.
 136
 137 =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.
 138
 139 =item C<gsl_histogram2d_clone($src)> - This function returns a pointer to a newly created histogram which is an exact copy of the histogram $src.
 140
 141 =item C<gsl_histogram2d_max_val($h)> - This function returns the maximum value contained in the histogram bins.
 142
 143 =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.
 144
 145 =item C<gsl_histogram2d_min_val($h)> - This function returns the minimum value contained in the histogram bins.
 146
 147 =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.
 148
 149 =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.
 150
 151 =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.
 152
 153 =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.
 154
 155 =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.
 156
 157 =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.
 158
 159 =item C<gsl_histogram2d_sum($h)> - This function returns the sum of all bin values. Negative bin values are included in the sum.
 160
 161 =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.
 162
 163 =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.
 164
 165 =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.
 166
 167 =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.
 168
 169 =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.
 170
 171 =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.
 172
 173 =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.
 174
 175 =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 fopen function) 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.
 176
 177 =item C<gsl_histogram2d_fread($stream $h)> - This function reads into the histogram $h from the stream $stream (opened with the fopen function) 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.
 178
 179 =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 fopen function) 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,
 180
 181 =over
 182
 183 =item xrange[0] xrange[1] yrange[0] yrange[1] bin(0,0)
 184
 185 =item xrange[0] xrange[1] yrange[1] yrange[2] bin(0,1)
 186
 187 =item xrange[0] xrange[1] yrange[2] yrange[3] bin(0,2)
 188
 189 =item ....
 190
 191 =item xrange[0] xrange[1] yrange[ny-1] yrange[ny] bin(0,ny-1)
 192
 193 =item
 194
 195 =item xrange[1] xrange[2] yrange[0] yrange[1] bin(1,0)
 196
 197 =item xrange[1] xrange[2] yrange[1] yrange[2] bin(1,1)
 198
 199 =item xrange[1] xrange[2] yrange[1] yrange[2] bin(1,2)
 200
 201 =item ....
 202
 203 =item xrange[1] xrange[2] yrange[ny-1] yrange[ny] bin(1,ny-1)
 204
 205 =item
 206
 207 =item ....
 208
 209 =item
 210
 211 =item xrange[nx-1] xrange[nx] yrange[0] yrange[1] bin(nx-1,0)
 212
 213 =item xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,1)
 214
 215 =item xrange[nx-1] xrange[nx] yrange[1] yrange[2] bin(nx-1,2)
 216
 217 =item ....
 218
 219 =item xrange[nx-1] xrange[nx] yrange[ny-1] yrange[ny] bin(nx-1,ny-1)
 220
 221 =back
 222
 223 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.
 224
 225 =item C<gsl_histogram2d_fscanf($stream, $h)> - This function reads formatted data from the stream $stream (opened with the fopen function) into the histogram $h. The data is assumed to be in the five-column format used by gsl_histogram2d_fprintf. The histogram $h must be preallocated with the correct lengths since the function uses the sizes of $h to determine how many numbers to read. The function returns 0 for success and $GSL_EFAILED if there was a problem reading from the file.
 226
 227 =item C<gsl_histogram2d_pdf_alloc($nx, $ny)> - This function allocates memory for a two-dimensional probability distribution of size $nx-by-$ny and returns a pointer to a newly initialized gsl_histogram2d_pdf struct. If insufficient memory is available a null pointer is returned and the error handler is invoked with an error code of $GSL_ENOMEM.
 228
 229 =item C<gsl_histogram2d_pdf_init($p, $h)> - This function initializes the two-dimensional probability distribution calculated $p from the histogram $h. If any of the bins of $h are negative then the error handler is invoked with an error code of GSL_EDOM because a probability distribution cannot contain negative values.
 230
 231 =item C<gsl_histogram2d_pdf_free($p)> - This function frees the two-dimensional probability distribution function $p and all of the memory associated with it.
 232
 233 =item C<gsl_histogram2d_pdf_sample($p, $r1, $r2)> - This function uses two uniform random numbers between zero and one, $r1 and $r2, to compute a single random sample from the two-dimensional probability distribution p. The function returns 0 if the operation succeeded, 1 otherwise followed by the x and y values of the sample.
 234
 235 =back
 236
 237 =head1 AUTHORS
 238
 239 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 240
 241 =head1 COPYRIGHT AND LICENSE
 242
 243 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 244
 245 This program is free software; you can redistribute it and/or modify it
 246 under the same terms as Perl itself.
 247
 248 =cut
 249
 250 %}