Merge branch 'bleed' of http://leto.net/code/Math-GSL into bleed
[Math-GSL.git] / pod / Statistics.pod
blob88daa8d9c1aa53362df2ac0e0420935773d16e79
1 %perlcode %{
2 @EXPORT_OK = qw/
3                gsl_stats_mean 
4                gsl_stats_variance 
5                gsl_stats_sd 
6                gsl_stats_variance_with_fixed_mean 
7                gsl_stats_sd_with_fixed_mean 
8                gsl_stats_tss 
9                gsl_stats_tss_m 
10                gsl_stats_absdev 
11                gsl_stats_skew 
12                gsl_stats_kurtosis 
13                gsl_stats_lag1_autocorrelation 
14                gsl_stats_covariance 
15                gsl_stats_correlation 
16                gsl_stats_variance_m 
17                gsl_stats_sd_m 
18                gsl_stats_absdev_m 
19                gsl_stats_skew_m_sd 
20                gsl_stats_kurtosis_m_sd 
21                gsl_stats_lag1_autocorrelation_m 
22                gsl_stats_covariance_m 
23                gsl_stats_wmean 
24                gsl_stats_wvariance 
25                gsl_stats_wsd 
26                gsl_stats_wvariance_with_fixed_mean 
27                gsl_stats_wsd_with_fixed_mean 
28                gsl_stats_wtss 
29                gsl_stats_wtss_m 
30                gsl_stats_wabsdev 
31                gsl_stats_wskew 
32                gsl_stats_wkurtosis 
33                gsl_stats_wvariance_m 
34                gsl_stats_wsd_m 
35                gsl_stats_wabsdev_m 
36                gsl_stats_wskew_m_sd 
37                gsl_stats_wkurtosis_m_sd 
38                gsl_stats_pvariance 
39                gsl_stats_ttest 
40                gsl_stats_max 
41                gsl_stats_min 
42                gsl_stats_minmax 
43                gsl_stats_max_index 
44                gsl_stats_min_index 
45                gsl_stats_minmax_index 
46                gsl_stats_median_from_sorted_data 
47                gsl_stats_quantile_from_sorted_data 
48                /;
49 our @EXPORT_int = qw/
50                gsl_stats_int_mean 
51                gsl_stats_int_variance 
52                gsl_stats_int_sd 
53                gsl_stats_int_variance_with_fixed_mean 
54                gsl_stats_int_sd_with_fixed_mean 
55                gsl_stats_int_tss 
56                gsl_stats_int_tss_m 
57                gsl_stats_int_absdev 
58                gsl_stats_int_skew 
59                gsl_stats_int_kurtosis 
60                gsl_stats_int_lag1_autocorrelation 
61                gsl_stats_int_covariance 
62                gsl_stats_int_correlation 
63                gsl_stats_int_variance_m 
64                gsl_stats_int_sd_m 
65                gsl_stats_int_absdev_m 
66                gsl_stats_int_skew_m_sd 
67                gsl_stats_int_kurtosis_m_sd 
68                gsl_stats_int_lag1_autocorrelation_m 
69                gsl_stats_int_covariance_m 
70                gsl_stats_int_pvariance 
71                gsl_stats_int_ttest 
72                gsl_stats_int_max 
73                gsl_stats_int_min 
74                gsl_stats_int_minmax 
75                gsl_stats_int_max_index 
76                gsl_stats_int_min_index 
77                gsl_stats_int_minmax_index 
78                gsl_stats_int_median_from_sorted_data 
79                gsl_stats_int_quantile_from_sorted_data 
80                /;
81 our @EXPORT_char = qw/
82                gsl_stats_char_mean 
83                gsl_stats_char_variance 
84                gsl_stats_char_sd 
85                gsl_stats_char_variance_with_fixed_mean 
86                gsl_stats_char_sd_with_fixed_mean 
87                gsl_stats_char_tss 
88                gsl_stats_char_tss_m 
89                gsl_stats_char_absdev 
90                gsl_stats_char_skew 
91                gsl_stats_char_kurtosis 
92                gsl_stats_char_lag1_autocorrelation 
93                gsl_stats_char_covariance 
94                gsl_stats_char_correlation 
95                gsl_stats_char_variance_m 
96                gsl_stats_char_sd_m 
97                gsl_stats_char_absdev_m 
98                gsl_stats_char_skew_m_sd 
99                gsl_stats_char_kurtosis_m_sd 
100                gsl_stats_char_lag1_autocorrelation_m 
101                gsl_stats_char_covariance_m 
102                gsl_stats_char_pvariance 
103                gsl_stats_char_ttest 
104                gsl_stats_char_max 
105                gsl_stats_char_min 
106                gsl_stats_char_minmax 
107                gsl_stats_char_max_index 
108                gsl_stats_char_min_index 
109                gsl_stats_char_minmax_index 
110                gsl_stats_char_median_from_sorted_data 
111                gsl_stats_char_quantile_from_sorted_data 
112              /;
113 push @EXPORT_OK, @EXPORT_int, @EXPORT_char;
114 %EXPORT_TAGS = ( 
115                 all => \@EXPORT_OK,
116                 int => \@EXPORT_int,
117                 char => \@EXPORT_char
118                );
119 __END__
121 =head1 NAME
123 Math::GSL::Statistics - Statistical functions 
125 =head1 SYNOPSIS
127     use Math::GSL::Statistics qw /:all/;
128         
129     my $data     = [17.2, 18.1, 16.5, 18.3, 12.6];
130     my $mean     = gsl_stats_mean($data, 1, 5);
131     my $variance = gsl_stats_variance($data, 1, 5);
132     my $largest  = gsl_stats_max($data, 1, 5);
133     my $smallest = gsl_stats_min($data, 1, 5);
134     print qq{
135     Dataset : @$data
136     Sample mean           $mean 
137     Estimated variance    $variance
138     Largest value         $largest
139     Smallest value        $smallest
140     };
143 =head1 DESCRIPTION
145 Here is a list of all the functions in this module :
147 =over 2
149 =item * C<gsl_stats_mean($data, $stride, $n)> - This function returns the arithmetic mean of the array reference $data, a dataset of length $n with stride $stride. The arithmetic mean, or sample mean, is denoted by \Hat\mu and defined as, \Hat\mu = (1/N) \sum x_i where x_i are the elements of the dataset $data. For samples drawn from a gaussian distribution the variance of \Hat\mu is \sigma^2 / N. 
151 =item * C<gsl_stats_variance($data, $stride, $n)> - This function returns the estimated, or sample, variance of data, an array reference of length $n with stride $stride. The estimated variance is denoted by \Hat\sigma^2 and is defined by, \Hat\sigma^2 = (1/(N-1)) \sum (x_i - \Hat\mu)^2 where x_i are the elements of the dataset data. Note that the normalization factor of 1/(N-1) results from the derivation of \Hat\sigma^2 as an unbiased estimator of the population variance \sigma^2. For samples drawn from a gaussian distribution the variance of \Hat\sigma^2 itself is 2 \sigma^4 / N. This function computes the mean via a call to gsl_stats_mean. If you have already computed the mean then you can pass it directly to gsl_stats_variance_m. 
153 =item * C<gsl_stats_sd($data, $stride, $n)>
155 =item * C<gsl_stats_sd_m($data, $stride, $n, $mean)>
157 The standard deviation is defined as the square root of the variance. These functions return the square root of the corresponding variance functions above.
159 =item * C<gsl_stats_variance_with_fixed_mean($data, $stride, $n, $mean)> - This function calculates the standard deviation of the array reference $data for a fixed population mean $mean. The result is the square root of the corresponding variance function.
161 =item * C<gsl_stats_sd_with_fixed_mean($data, $stride, $n, $mean)> - This function computes an unbiased estimate of the variance of data when the population mean $mean of the underlying distribution is known a priori. In this case the estimator for the variance uses the factor 1/N and the sample mean \Hat\mu is replaced by the known population mean \mu, \Hat\sigma^2 = (1/N) \sum (x_i - \mu)^2
163 =item * C<gsl_stats_tss($data, $stride, $n)>
165 =item * C<gsl_stats_tss_m($data, $stride, $n, $mean)>
167 These functions return the total sum of squares (TSS) of data about the mean. For gsl_stats_tss_m the user-supplied value of mean is used, and for gsl_stats_tss it is computed using gsl_stats_mean. TSS =  \sum (x_i - mean)^2
169 =item * C<gsl_stats_absdev($data, $stride, $n)> - This function computes the absolute deviation from the mean of data, a dataset of length $n with stride $stride. The absolute deviation from the mean is defined as, absdev  = (1/N) \sum |x_i - \Hat\mu| where x_i are the elements of the array reference $data. The absolute deviation from the mean provides a more robust measure of the width of a distribution than the variance. This function computes the mean of data via a call to gsl_stats_mean. 
171 =item * C<gsl_stats_skew($data, $stride, $n)> - This function computes the skewness of $data, a dataset in the form of an array reference of length $n with stride $stride. The skewness is defined as, skew = (1/N) \sum ((x_i - \Hat\mu)/\Hat\sigma)^3 where x_i are the elements of the dataset $data. The skewness measures the asymmetry of the tails of a distribution. The function computes the mean and estimated standard deviation of data via calls to gsl_stats_mean and gsl_stats_sd. 
173 =item * C<gsl_stats_skew_m_sd($data, $stride, $n, $mean, $sd)> - This function computes the skewness of the array reference $data using the given values of the mean $mean and standard deviation $sd, skew = (1/N) \sum ((x_i - mean)/sd)^3. These functions are useful if you have already computed the mean and standard deviation of $data and want to avoid recomputing them. 
175 =item * C<gsl_stats_kurtosis($data, $stride, $n)> - This function computes the kurtosis of data, an array reference of length $n with stride $stride. The kurtosis is defined as, kurtosis = ((1/N) \sum ((x_i - \Hat\mu)/\Hat\sigma)^4)  - 3. The kurtosis measures how sharply peaked a distribution is, relative to its width. The kurtosis is normalized to zero for a gaussian distribution. 
177 =item * C<gsl_stats_kurtosis_m_sd($data, $stride, $n, $mean, $sd)> - This function computes the kurtosis of the array reference $data using the given values of the mean $mean and standard deviation $sd, kurtosis = ((1/N) \sum ((x_i - mean)/sd)^4) - 3. This function is useful if you have already computed the mean and standard deviation of data and want to avoid recomputing them. 
179 =item * C<gsl_stats_lag1_autocorrelation($data, $stride, $n)> - This function computes the lag-1 autocorrelation of the array reference data.
180  a_1 = {\sum_{i = 1}^{n} (x_{i} - \Hat\mu) (x_{i-1} - \Hat\mu)
181   \over
182  \sum_{i = 1}^{n} (x_{i} - \Hat\mu) (x_{i} - \Hat\mu)}
184 =item * C<gsl_stats_lag1_autocorrelation_m($data, $stride, $n, $mean)> - This function computes the lag-1 autocorrelation of the array reference $data using the given value of the mean $mean.
186 =item * C<gsl_stats_covariance($data1, $stride1, $data2, $stride2, $n)> - This function computes the covariance of the array reference $data1 and $data2 which must both be of the same length $n. covar = (1/(n - 1)) \sum_{i = 1}^{n} (x_i - \Hat x) (y_i - \Hat y)
188 =item * C<gsl_stats_covariance_m($data1, $stride1, $data2, $stride2, $n, $mean1, $mean2)> - This function computes the covariance of the array reference $data1 and $data2 using the given values of the means, $mean1 and $mean2. This is useful if you have already computed the means of $data1 and $data2 and want to avoid recomputing them.
190 =item * C<gsl_stats_correlation($data1, $stride1, $data2, $stride2, $n)> - This function efficiently computes the Pearson correlation coefficient between the array reference $data1 and $data2 which must both be of the same length $n.
191  r = cov(x, y) / (\Hat\sigma_x \Hat\sigma_y)
192    = {1/(n-1) \sum (x_i - \Hat x) (y_i - \Hat y)
193       \over
194       \sqrt{1/(n-1) \sum (x_i - \Hat x)^2} \sqrt{1/(n-1) \sum (y_i - \Hat y)^2}
195      }
196          
197 =item * C<gsl_stats_variance_m($data, $stride, $n, $mean)> - This function returns the sample variance of $data, an array reference, relative to the given value of $mean. The function is computed with \Hat\mu replaced by the value of mean that you supply, \Hat\sigma^2 = (1/(N-1)) \sum (x_i - mean)^2
199 =item * C<gsl_stats_absdev_m($data, $stride, $n, $mean)> - This function computes the absolute deviation of the dataset $data, an array refrence, relative to the given value of $mean, absdev  = (1/N) \sum |x_i - mean|. This function is useful if you have already computed the mean of data (and want to avoid recomputing it), or wish to calculate the absolute deviation relative to another value (such as zero, or the median). 
201 =item * C<gsl_stats_wmean($w, $wstride, $data, $stride, $n)> - This function returns the weighted mean of the dataset $data array reference with stride $stride and length $n, using the set of weights $w, which is an array reference, with stride $wstride and length $n. The weighted mean is defined as, \Hat\mu = (\sum w_i x_i) / (\sum w_i)
203 =item * C<gsl_stats_wvariance($w, $wstride, $data, $stride, $n)> - This function returns the estimated variance of the dataset $data, which is the dataset, with stride $stride and length $n, using the set of weights $w (as an array reference) with stride $wstride and length $n. The estimated variance of a weighted dataset is defined as,  \Hat\sigma^2 = ((\sum w_i)/((\sum w_i)^2 - \sum (w_i^2))) \sum w_i (x_i - \Hat\mu)^2. Note that this expression reduces to an unweighted variance with the familiar 1/(N-1) factor when there are N equal non-zero weights. 
205 =item * C<gsl_stats_wvariance_m($w, $wstride, $data, $stride, $n, $wmean, $wsd)> - This function returns the estimated variance of the weighted dataset $data (which is an array reference) using the given weighted mean $wmean.
207 =item * C<gsl_stats_wsd($w, $wstride, $data, $stride, $n)> - The standard deviation is defined as the square root of the variance. This function returns the square root of the corresponding variance function gsl_stats_wvariance above.
209 =item * C<gsl_stats_wsd_m($w, $wstride, $data, $stride, $n, $wmean)> - This function returns the square root of the corresponding variance function gsl_stats_wvariance_m above.
211 =item * C<gsl_stats_wvariance_with_fixed_mean($w, $wstride, $data, $stride, $n, $mean)> - This function computes an unbiased estimate of the variance of weighted dataset $data (which is an array reference) when the population mean $mean of the underlying distribution is known a priori. In this case the estimator for the variance replaces the sample mean \Hat\mu by the known population mean \mu, \Hat\sigma^2 = (\sum w_i (x_i - \mu)^2) / (\sum w_i)
213 =item * C<gsl_stats_wsd_with_fixed_mean($w, $wstride, $data, $stride, $n, $mean)> - The standard deviation is defined as the square root of the variance. This function returns the square root of the corresponding variance function above.
215 =item * C<gsl_stats_wtss($w, $wstride, $data, $stride, $n)>
217 =item * C<gsl_stats_wtss_m($w, $wstride, $data, $stride, $n, $wmean)> - These functions return the weighted total sum of squares (TSS) of data about the weighted mean. For gsl_stats_wtss_m the user-supplied value of $wmean is used, and for gsl_stats_wtss it is computed using gsl_stats_wmean. TSS =  \sum w_i (x_i - wmean)^2
219 =item * C<gsl_stats_wabsdev($w, $wstride, $data, $stride, $n)> - This function computes the weighted absolute deviation from the weighted mean of $data, which is an array reference. The absolute deviation from the mean is defined as, absdev = (\sum w_i |x_i - \Hat\mu|) / (\sum w_i)
221 =item * C<gsl_stats_wabsdev_m($w, $wstride, $data, $stride, $n, $wmean)> - This function computes the absolute deviation of the weighted dataset $data (an array reference) about the given weighted mean $wmean.
223 =item * C<gsl_stats_wskew($w, $wstride, $data, $stride, $n)> - This function computes the weighted skewness of the dataset $data, an array reference. skew = (\sum w_i ((x_i - xbar)/\sigma)^3) / (\sum w_i)
225 =item * C<gsl_stats_wskew_m_sd($w, $wstride, $data, $stride, $n, $wmean, $wsd)> - This function computes the weighted skewness of the dataset $data using the given values of the weighted mean and weighted standard deviation, $wmean and $wsd.
227 =item * C<gsl_stats_wkurtosis($w, $wstride, $data, $stride, $n)> - This function computes the weighted kurtosis of the dataset $data, an array reference. kurtosis = ((\sum w_i ((x_i - xbar)/sigma)^4) / (\sum w_i)) - 3
229 =item * C<gsl_stats_wkurtosis_m_sd($w, $wstride, $data, $stride, $n, $wmean, $wsd)> - This function computes the weighted kurtosis of the dataset $data, an array reference, using the given values of the weighted mean and weighted standard deviation, $wmean and $wsd. 
231 =item * C<gsl_stats_pvariance($data, $stride, $n, $data2, $stride2, $n2)>
233 =item * C<gsl_stats_ttest($data1, $stride1, $n1, $data2, $stride2, $n2)>
235 =item * C<gsl_stats_max($data, $stride, $n)> - This function returns the maximum value in the $data array reference, a dataset of length $n with stride $stride. The maximum value is defined as the value of the element x_i which satisfies x_i >= x_j for all j. If you want instead to find the element with the largest absolute magnitude you will need to apply fabs or abs to your data before calling this function. 
237 =item * C<gsl_stats_min($data, $stride, $n)> - This function returns the minimum value in $data (which is an array reference) a dataset of length $n with stride $stride. The minimum value is defined as the value of the element x_i which satisfies x_i <= x_j for all j. If you want instead to find the element with the smallest absolute magnitude you will need to apply fabs or abs to your data before calling this function. 
239 =item * C<gsl_stats_minmax($data, $stride, $n)> - This function finds both the minimum and maximum values in $data, which is an array reference, in a single pass and returns them in this order.
241 =item * C<gsl_stats_max_index($data, $stride, $n)> - This function returns the index of the maximum value in $data array reference, a dataset of length $n with stride $stride. The maximum value is defined as the value of the element x_i which satisfies x_i >= x_j for all j. When there are several equal maximum elements then the first one is chosen.
243 =item * C<gsl_stats_min_index($data, $stride, $n)> - This function returns the index of the minimum value in $data array reference, a dataset of length $n with stride $stride. The minimum value is defined as the value of the element x_i which satisfies x_i <= x_j for all j. When there are several equal minimum elements then the first one is chosen.
245 =item * C<gsl_stats_minmax_index($data, $stride, $n)> - This function returns the indexes of the minimum and maximum values in $data, an array reference in a single pass. The value are returned in this order. 
247 =item * C<gsl_stats_median_from_sorted_data($sorted_data, $stride, $n)> - This function returns the median value of $sorted_data (which is an array reference), a dataset of length $n with stride $stride. The elements of the array must be in ascending numerical order. There are no checks to see whether the data are sorted, so the function gsl_sort should always be used first. This function can be found in the Math::GSL::Sort module.  When the dataset has an odd number of elements the median is the value of element (n-1)/2. When the dataset has an even number of elements the median is the mean of the two nearest middle values, elements (n-1)/2 and n/2. Since the algorithm for computing the median involves interpolation this function always returns a floating-point number, even for integer data types.
249 =item * C<gsl_stats_quantile_from_sorted_data($sorted_data, $stride, $n, $f)> - This function returns a quantile value of $sorted_data, a double-precision array reference of length $n with stride $stride. The elements of the array must be in ascending numerical order. The quantile is determined by the f, a fraction between 0 and 1. For example, to compute the value of the 75th percentile f should have the value 0.75. There are no checks to see whether the data are sorted, so the function gsl_sort should always be used first. This function can be found in the Math::GSL::Sort module. The quantile is found by interpolation, using the formula quantile = (1 - \delta) x_i + \delta x_{i+1} where i is floor((n - 1)f) and \delta is (n-1)f - i. Thus the minimum value of the array (data[0*stride]) is given by f equal to zero, the maximum value (data[(n-1)*stride]) is given by f equal to one and the median value is given by f equal to 0.5. Since the algorithm for computing quantiles involves interpolation this function always returns a floating-point number, even for integer data types. 
251 =back
253 The following function are simply variants for int and char of the last functions:
255 =over 4
257 =item * C<gsl_stats_int_mean >
259 =item * C<gsl_stats_int_variance >
261 =item * C<gsl_stats_int_sd >
263 =item * C<gsl_stats_int_variance_with_fixed_mean >
265 =item * C<gsl_stats_int_sd_with_fixed_mean >
267 =item * C<gsl_stats_int_tss >
269 =item * C<gsl_stats_int_tss_m >
271 =item * C<gsl_stats_int_absdev >
273 =item * C<gsl_stats_int_skew >
275 =item * C<gsl_stats_int_kurtosis >
277 =item * C<gsl_stats_int_lag1_autocorrelation >
279 =item * C<gsl_stats_int_covariance >
281 =item * C<gsl_stats_int_correlation >
283 =item * C<gsl_stats_int_variance_m >
285 =item * C<gsl_stats_int_sd_m >
287 =item * C<gsl_stats_int_absdev_m >
289 =item * C<gsl_stats_int_skew_m_sd >
291 =item * C<gsl_stats_int_kurtosis_m_sd >
293 =item * C<gsl_stats_int_lag1_autocorrelation_m >
295 =item * C<gsl_stats_int_covariance_m >
297 =item * C<gsl_stats_int_pvariance >
299 =item * C<gsl_stats_int_ttest >
301 =item * C<gsl_stats_int_max >
303 =item * C<gsl_stats_int_min >
305 =item * C<gsl_stats_int_minmax >
307 =item * C<gsl_stats_int_max_index >
309 =item * C<gsl_stats_int_min_index >
311 =item * C<gsl_stats_int_minmax_index >
313 =item * C<gsl_stats_int_median_from_sorted_data >
315 =item * C<gsl_stats_int_quantile_from_sorted_data >
317 =item * C<gsl_stats_char_mean >
319 =item * C<gsl_stats_char_variance >
321 =item * C<gsl_stats_char_sd >
323 =item * C<gsl_stats_char_variance_with_fixed_mean >
325 =item * C<gsl_stats_char_sd_with_fixed_mean >
327 =item * C<gsl_stats_char_tss >
329 =item * C<gsl_stats_char_tss_m >
331 =item * C<gsl_stats_char_absdev >
333 =item * C<gsl_stats_char_skew >
335 =item * C<gsl_stats_char_kurtosis >
337 =item * C<gsl_stats_char_lag1_autocorrelation >
339 =item * C<gsl_stats_char_covariance >
341 =item * C<gsl_stats_char_correlation >
343 =item * C<gsl_stats_char_variance_m >
345 =item * C<gsl_stats_char_sd_m >
347 =item * C<gsl_stats_char_absdev_m >
349 =item * C<gsl_stats_char_skew_m_sd >
351 =item * C<gsl_stats_char_kurtosis_m_sd >
353 =item * C<gsl_stats_char_lag1_autocorrelation_m >
355 =item * C<gsl_stats_char_covariance_m >
357 =item * C<gsl_stats_char_pvariance >
359 =item * C<gsl_stats_char_ttest >
361 =item * C<gsl_stats_char_max >
363 =item * C<gsl_stats_char_min >
365 =item * C<gsl_stats_char_minmax >
367 =item * C<gsl_stats_char_max_index >
369 =item * C<gsl_stats_char_min_index >
371 =item * C<gsl_stats_char_minmax_index >
373 =item * C<gsl_stats_char_median_from_sorted_data >
375 =item * C<gsl_stats_char_quantile_from_sorted_data >
377 =back
379 You have to add the functions you want to use inside the qw /put_funtion_here /. 
380 You can also write use Math::GSL::Statistics qw/:all/; to use all avaible functions of the module. 
381 Other tags are also avaible, here is a complete list of all tags for this module :
383 =over
385 =item all
387 =item int
389 =item char
391 =back
393 For more informations on the functions, we refer you to the GSL offcial
394 documentation: L<http://www.gnu.org/software/gsl/manual/html_node/>
396  Tip : search on google: site:http://www.gnu.org/software/gsl/manual/html_node/ name_of_the_function_you_want
399 =head1 AUTHORS
401 Jonathan Leto <jonathan@leto.net> and Thierry Moisan <thierry.moisan@gmail.com>
403 =head1 COPYRIGHT AND LICENSE
405 Copyright (C) 2008 Jonathan Leto and Thierry Moisan
407 This program is free software; you can redistribute it and/or modify it
408 under the same terms as Perl itself.
410 =cut