Histogram.i

   1 %module "Math::GSL::Histogram"
   2 %include "typemaps.i"
   3 %include "gsl_typemaps.i"
   4
   5 FILE * fopen(char *, char *);
   6 int fclose(FILE *);
   7
   8 %{
   9     #include "gsl/gsl_histogram.h"
  10 %}
  11
  12 %include "gsl/gsl_histogram.h"
  13
  14
  15 %perlcode %{
  16 @EXPORT_OK = qw/fopen fclose
  17                gsl_histogram_alloc
  18                gsl_histogram_calloc
  19                gsl_histogram_calloc_uniform
  20                gsl_histogram_free
  21                gsl_histogram_increment
  22                gsl_histogram_accumulate
  23                gsl_histogram_find
  24                gsl_histogram_get
  25                gsl_histogram_get_range
  26                gsl_histogram_max
  27                gsl_histogram_min
  28                gsl_histogram_bins
  29                gsl_histogram_reset
  30                gsl_histogram_calloc_range
  31                gsl_histogram_set_ranges
  32                gsl_histogram_set_ranges_uniform
  33                gsl_histogram_memcpy
  34                gsl_histogram_clone
  35                gsl_histogram_max_val
  36                gsl_histogram_max_bin
  37                gsl_histogram_min_val
  38                gsl_histogram_min_bin
  39                gsl_histogram_equal_bins_p
  40                gsl_histogram_add
  41                gsl_histogram_sub
  42                gsl_histogram_mul
  43                gsl_histogram_div
  44                gsl_histogram_scale
  45                gsl_histogram_shift
  46                gsl_histogram_sigma
  47                gsl_histogram_mean
  48                gsl_histogram_sum
  49                gsl_histogram_fwrite
  50                gsl_histogram_fread
  51                gsl_histogram_fprintf
  52                gsl_histogram_fscanf
  53                gsl_histogram_pdf_alloc
  54                gsl_histogram_pdf_init
  55                gsl_histogram_pdf_free
  56                gsl_histogram_pdf_sample
  57              /;
  58 %EXPORT_TAGS = ( all => [ @EXPORT_OK ] );
  59
  60 =head1 NAME
  61
  62 Math::GSL::Histogram - Create and manipulate histograms of data
  63
  64 =head1 SYNOPSIS
  65
  66     use Math::GSL::Histogram qw/:all/;
  67
  68     my $H = gsl_histogram_alloc(100);
  69     gsl_histogram_set_ranges_uniform($H,0,101);
  70     gsl_histogram_increment($H, -50 );  # ignored
  71     gsl_histogram_increment($H, 70 );
  72     gsl_histogram_increment($H, 85.2 );
  73
  74     my $G = gsl_histogram_clone($H);
  75     my $value = gsl_histogram_get($G, 70);
  76     my ($max,$min) = (gsl_histogram_min_val($H), gsl_histogram_max_val($H) );
  77     my $sum = gsl_histogram_sum($H);
  78
  79 =cut
  80
  81 =head1 DESCRIPTION
  82
  83 Here is a list of all the functions included in this module :
  84
  85 =over 1
  86
  87 =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.
  88
  89 =item C<gsl_histogram_calloc >
  90
  91 =item C<gsl_histogram_calloc_uniform >
  92
  93 =item C<gsl_histogram_free($h)> - This function frees the histogram $h and all of the memory associated with it.
  94
  95 =item C<gsl_histogram_increment >
  96
  97 =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.
  98
  99 =item C<gsl_histogram_find >
 100
 101 =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.
 102
 103 =item C<gsl_histogram_get_range >
 104
 105 =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.
 106
 107 =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.
 108
 109 =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.
 110
 111 =item C<gsl_histogram_reset($h)> - This function resets all the bins in the histogram $h to zero.
 112
 113 =item C<gsl_histogram_calloc_range >
 114
 115 =item C<gsl_histogram_set_ranges >
 116
 117 =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,
 118 =over
 119
 120 =item  bin[0] corresponds to xmin <= x < xmin + d
 121
 122 =item  bin[1] corresponds to xmin + d <= x < xmin + 2 d
 123
 124 =item  ......
 125
 126 =item  bin[n-1] corresponds to xmin + (n-1)d <= x < xmax
 127
 128 =back
 129
 130 where d is the bin spacing, d = (xmax-xmin)/n.
 131
 132 =over
 133
 134 =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.
 135
 136 =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.
 137
 138 =item C<gsl_histogram_max_val($h)> - This function returns the maximum value contained in the histogram bins.
 139
 140 =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.
 141
 142 =item C<gsl_histogram_min_val($h)> - This function returns the minimum value contained in the histogram bins.
 143
 144 =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.
 145
 146 =item C<gsl_histogram_equal_bins_p >
 147
 148 =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.
 149
 150 =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.
 151
 152 =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.
 153
 154 =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.
 155
 156 =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.
 157
 158 =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.
 159
 160 =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.
 161
 162 =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.
 163
 164 =item C<gsl_histogram_sum($h)> - This function returns the sum of all bin values. Negative bin values are included in the sum.
 165
 166 =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 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.
 167
 168 =item C<gsl_histogram_fread($stream, $h)> - This function reads into the histogram $h from the open stream stream 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.
 169
 170 =item C<gsl_histogram_fprintf >
 171
 172 =item C<gsl_histogram_fscanf >
 173
 174 =item C<gsl_histogram_pdf_alloc >
 175
 176 =item C<gsl_histogram_pdf_init >
 177
 178 =item C<gsl_histogram_pdf_free >
 179
 180 =item C<gsl_histogram_pdf_sample >
 181
 182 =back
 183
 184 =head1 AUTHORS
 185
 186 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
 187
 188 =head1 COPYRIGHT AND LICENSE
 189
 190 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
 191
 192 This program is free software; you can redistribute it and/or modify it
 193 under the same terms as Perl itself.
 194
 195 =cut
 196
 197 %}