Histogram.i

   1 %module "Math::GSL::Histogram"
   2 %include "typemaps.i"
   3 %include "gsl_typemaps.i"
   4
   5 %apply double *OUTPUT { double * lower, double * upper, size_t * i};
   6
   7 %{
   8     #include "gsl/gsl_histogram.h"
   9 %}
  10
  11 %include "gsl/gsl_histogram.h"
  12
  13
  14 %perlcode %{
  15 @EXPORT_OK = qw/
  16                gsl_histogram_alloc
  17                gsl_histogram_calloc
  18                gsl_histogram_calloc_uniform
  19                gsl_histogram_free
  20                gsl_histogram_increment
  21                gsl_histogram_accumulate
  22                gsl_histogram_find
  23                gsl_histogram_get
  24                gsl_histogram_get_range
  25                gsl_histogram_max
  26                gsl_histogram_min
  27                gsl_histogram_bins
  28                gsl_histogram_reset
  29                gsl_histogram_calloc_range
  30                gsl_histogram_set_ranges
  31                gsl_histogram_set_ranges_uniform
  32                gsl_histogram_memcpy
  33                gsl_histogram_clone
  34                gsl_histogram_max_val
  35                gsl_histogram_max_bin
  36                gsl_histogram_min_val
  37                gsl_histogram_min_bin
  38                gsl_histogram_equal_bins_p
  39                gsl_histogram_add
  40                gsl_histogram_sub
  41                gsl_histogram_mul
  42                gsl_histogram_div
  43                gsl_histogram_scale
  44                gsl_histogram_shift
  45                gsl_histogram_sigma
  46                gsl_histogram_mean
  47                gsl_histogram_sum
  48                gsl_histogram_fwrite
  49                gsl_histogram_fread
  50                gsl_histogram_fprintf
  51                gsl_histogram_fscanf
  52                gsl_histogram_pdf_alloc
  53                gsl_histogram_pdf_init
  54                gsl_histogram_pdf_free
  55                gsl_histogram_pdf_sample
  56              /;
  57 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
  58
  59 =head1 NAME
  60
  61 Math::GSL::Histogram - Create and manipulate histograms of data
  62
  63 =head1 SYNOPSIS
  64
  65     use Math::GSL::Histogram qw/:all/;
  66
  67     my $H = gsl_histogram_alloc(100);
  68     gsl_histogram_set_ranges_uniform($H,0,101);
  69     gsl_histogram_increment($H, -50 );  # ignored
  70     gsl_histogram_increment($H, 70 );
  71     gsl_histogram_increment($H, 85.2 );
  72
  73     my $G = gsl_histogram_clone($H);
  74     my $value = gsl_histogram_get($G, 70);
  75     my ($max,$min) = (gsl_histogram_min_val($H), gsl_histogram_max_val($H) );
  76     my $sum = gsl_histogram_sum($H);
  77
  78 =cut
  79
  80 =head1 DESCRIPTION
  81
  82 Here is a list of all the functions included in this module :
  83
  84 =over 1
  85
  86 =item C<gsl_histogram_alloc($n)> - This function allocates memory for a histogram with $n bins, and returns a pointer to a newly created gsl_histogram struct. 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.
  87
  88 =item C<gsl_histogram_calloc >
  89
  90 =item C<gsl_histogram_calloc_uniform >
  91
  92 =item C<gsl_histogram_free($h)> - This function frees the histogram $h and all of the memory associated with it.
  93
  94 =item C<gsl_histogram_increment($h, $x)> - This function updates the histogram $h by adding one (1.0) to the bin whose range contains the coordinate $x. If $x lies in the valid range of the histogram then the function returns zero to indicate success. If $x is less than the lower limit of the histogram then the function returns $GSL_EDOM, and none of bins are modified. Similarly, if the value of $x is greater than or equal to the upper limit of the histogram then the function returns $GSL_EDOM, and none of the bins are modified. The error handler is not called, however, since it is often necessary to compute histograms for a small range of a larger dataset, ignoring the values outside the range of interest.
  95
  96 =item C<gsl_histogram_accumulate($h, $x, $weight)> - This function is similar to gsl_histogram_increment but increases the value of the appropriate bin in the histogram $h by the floating-point number weight.
  97
  98 =item C<gsl_histogram_find($h, $x)> - This function finds the bin number which covers the coordinate $x in the histogram $h. 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 $x is found in the range of the histogram then the function returns the bin number and returns $GSL_SUCCESS. If $x lies outside the valid range of the histogram then the function returns $GSL_EDOM and the error handler is invoked.
  99
 100 =item C<gsl_histogram_get($h, $i)> - This function returns the contents of the $i-th bin of the histogram $h. 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 and the function returns 0.
 101
 102 =item C<gsl_histogram_get_range($h, $i)> - This function finds the upper and lower range limits of the $i-th bin of the histogram $h. If the index $i is valid then the corresponding range limits are returned after the 0 in this order : lower and then upper. 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 i lies outside the valid range of indices for the histogram then the error handler is called and the function returns an error code of $GSL_EDOM.
 103
 104 =item C<gsl_histogram_max($h)> - This function returns the maximum upper limit of the histogram $h. It provides a way of determining this value without accessing the gsl_histogram struct directly.
 105
 106 =item C<gsl_histogram_min($h)> - This function returns the minimum lower range limit of the histogram $h. It provides a way of determining this value without accessing the gsl_histogram struct directly.
 107
 108 =item C<gsl_histogram_bins($h)> - This function returns the number of bins of the histogram $h limit. It provides a way of determining this value without accessing the gsl_histogram struct directly.
 109
 110 =item C<gsl_histogram_reset($h)> - This function resets all the bins in the histogram $h to zero.
 111
 112 =item C<gsl_histogram_calloc_range>
 113
 114 =item C<gsl_histogram_set_ranges($h, $range, $size)> - This function sets the ranges of the existing histogram $h using the array $range of size $size. The values of the histogram bins are reset to zero. The $range array should contain the desired bin limits. The ranges can be arbitrary, subject to the restriction that they are monotonically increasing. Note that the size of the $range array should be defined to be one element bigger than the number of bins. The additional element is required for the upper value of the final bin.
 115
 116 =item C<gsl_histogram_set_ranges_uniform($h, $xmin, $xmax)> - This function sets the ranges of the existing histogram $h to cover the range $xmin to $xmax uniformly. The values of the histogram bins are reset to zero. The bin ranges are shown in the table below,
 117
 118 =back
 119
 120 =over
 121
 122 =item  bin[0] corresponds to xmin <= x < xmin + d
 123
 124 =item  bin[1] corresponds to xmin + d <= x < xmin + 2 d
 125
 126 =item  ......
 127
 128 =item  bin[n-1] corresponds to xmin + (n-1)d <= x < xmax
 129
 130 =back
 131
 132 where d is the bin spacing, d = (xmax-xmin)/n.
 133
 134 =over
 135
 136 =item C<gsl_histogram_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.
 137
 138 =item C<gsl_histogram_clone($src)> - This function returns a pointer to a newly created histogram which is an exact copy of the histogram $src.
 139
 140 =item C<gsl_histogram_max_val($h)> - This function returns the maximum value contained in the histogram bins.
 141
 142 =item C<gsl_histogram_max_bin($h)> - This function returns the index of the bin containing the maximum value. In the case where several bins contain the same maximum value the smallest index is returned.
 143
 144 =item C<gsl_histogram_min_val($h)> - This function returns the minimum value contained in the histogram bins.
 145
 146 =item C<gsl_histogram_min_bin($h)> - This function returns the index of the bin containing the minimum value. In the case where several bins contain the same maximum value the smallest index is returned.
 147
 148 =item C<gsl_histogram_equal_bins_p($h1, $h2)> - This function returns 1 if the all of the individual bin ranges of the two histograms are identical, and 0 otherwise.
 149
 150 =item C<gsl_histogram_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) = h_1(i) + h_2(i). The two histograms must have identical bin ranges.
 151
 152 =item C<gsl_histogram_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) = h_1(i) - h_2(i). The two histograms must have identical bin ranges.
 153
 154 =item C<gsl_histogram_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) = h_1(i) * h_2(i). The two histograms must have identical bin ranges.
 155
 156 =item C<gsl_histogram_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) = h_1(i) / h_2(i). The two histograms must have identical bin ranges.
 157
 158 =item C<gsl_histogram_scale($h, $scale)> - This function multiplies the contents of the bins of histogram $h by the constant $scale, i.e. h'_1(i) = h_1(i) * scale.
 159
 160 =item C<gsl_histogram_shift($h, $offset)> - This function shifts the contents of the bins of histogram $h by the constant $offset, i.e. h'_1(i) = h_1(i) + offset.
 161
 162 =item C<gsl_histogram_sigma($h)> - This function returns the standard deviation of the histogrammed variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation. The accuracy of the result is limited by the bin width.
 163
 164 =item C<gsl_histogram_mean($h)> - This function returns the mean of the histogrammed variable, where the histogram is regarded as a probability distribution. Negative bin values are ignored for the purposes of this calculation. The accuracy of the result is limited by the bin width.
 165
 166 =item C<gsl_histogram_sum($h)> - This function returns the sum of all bin values. Negative bin values are included in the sum.
 167
 168 =item C<gsl_histogram_fwrite($stream, $h)> - This function writes the ranges and bins of the histogram $h to the stream $stream, which has been opened by 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_histogram_fread($stream, $h)> - This function reads into the histogram $h from the open stream $stream, which has been opened by 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 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_histogram_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 (from 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 three columns, and the columns are separated by spaces, like this,
 173
 174 =over
 175
 176 =item range[0] range[1] bin[0]
 177
 178 =item range[1] range[2] bin[1]
 179
 180 =item range[2] range[3] bin[2]
 181
 182 =item ....
 183
 184 =item range[n-1] range[n] bin[n-1]
 185
 186 =back
 187
 188 The values of the ranges are formatted using range_format and the value of the bins are formatted using bin_format. Each line contains the lower and upper limit of the range of the bins and the value of the bin itself. Since the upper limit of one bin is the lower limit of the next there is duplication of these values between lines but this allows the histogram to be manipulated with line-oriented tools.
 189
 190 =item C<gsl_histogram_fscanf($stream, $h)> - This function reads formatted data from the stream $stream, which has been opened by the gsl_fopen function from the Math::GSL module, into the histogram $h. The data is assumed to be in the three-column format used by gsl_histogram_fprintf. The histogram $h must be preallocated with the correct length since the function uses the size 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.
 191
 192 =item C<gsl_histogram_pdf_alloc($n)> - This function allocates memory for a probability distribution with $n bins and returns a pointer to a newly initialized gsl_histogram_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.
 193
 194 =item C<gsl_histogram_pdf_init($p, $h)> - This function initializes the probability distribution $p with the contents of 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.
 195
 196 =item C<gsl_histogram_pdf_free($p)> - This function frees the probability distribution function $p and all of the memory associated with it.
 197
 198 =item C<gsl_histogram_pdf_sample($p, $r)> -     This function uses $r, a uniform random number between zero and one, to compute a single random sample from the probability distribution $p. The algorithm used to compute the sample s is given by the following formula, s = range[i] + delta * (range[i+1] - range[i]) where i is the index which satisfies sum[i] <= r < sum[i+1] and delta is (r - sum[i])/(sum[i+1] - sum[i]).
 199
 200 =back
 201
 202 =head1 EXAMPLES
 203
 204  The following example shows how to create a histogram with logarithmic bins with ranges [1,10), [10,100) and [100,1000).
 205
 206  $h = gsl_histogram_alloc (3);
 207
 208  # bin[0] covers the range 1 <= x < 10
 209  # bin[1] covers the range 10 <= x < 100
 210  # bin[2] covers the range 100 <= x < 1000
 211
 212  $range = [ 1.0, 10.0, 100.0, 1000.0 ];
 213
 214  gsl_histogram_set_ranges($h, $range, 4);
 215
 216 =head1 AUTHORS
 217
 218 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 219
 220 =head1 COPYRIGHT AND LICENSE
 221
 222 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 223
 224 This program is free software; you can redistribute it and/or modify it
 225 under the same terms as Perl itself.
 226
 227 =cut
 228
 229 %}