statistics.texi

开放gsl矩阵运算

@deftypefn Statistics double gsl_stats_wvariance (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function returns the estimated variance of the dataset @var{data}
with stride @var{stride} and length @var{n}, using the set of weights
@var{w} with stride @var{wstride} and length @var{n}.  The estimated
variance of a weighted dataset is defined as,

@tex
\beforedisplay
$$
\Hat\sigma^2 = {{\sum w_i} \over {(\sum w_i)^2 - \sum (w_i^2)}} 
                \sum w_i (x_i - \Hat\mu)^2
$$
\afterdisplay
@end tex
@ifinfo
@example
\Hat\sigma^2 = ((\sum w_i)/((\sum w_i)^2 - \sum (w_i^2))) 
                \sum w_i (x_i - \Hat\mu)^2
@end example
@end ifinfo
@noindent
Note that this expression reduces to an unweighted variance with the
familiar @math{1/(N-1)} factor when there are @math{N} equal non-zero
weights.
@end deftypefn

@deftypefn Statistics double gsl_stats_wvariance_m (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n}, double @var{wmean})
This function returns the estimated variance of the weighted dataset
@var{data} using the given weighted mean @var{wmean}.
@end deftypefn

@deftypefn Statistics double gsl_stats_wsd (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
The standard deviation is defined as the square root of the variance.
This function returns the square root of the corresponding variance
function @code{gsl_stats_wvariance} above.
@end deftypefn

@deftypefn Statistics double gsl_stats_wsd_m (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n}, double @var{wmean})
This function returns the square root of the corresponding variance
function @code{gsl_stats_wvariance_m} above.
@end deftypefn

@deftypefn Statistics double gsl_stats_wvariance_with_fixed_mean (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function computes an unbiased estimate of the variance of weighted
dataset @var{data} when the population mean @var{mean} of the underlying
distribution is known @emph{a priori}.  In this case the estimator for
the variance replaces the sample mean @math{\Hat\mu} by the known
population mean @math{\mu},

@tex
\beforedisplay
$$
\Hat\sigma^2 = {{\sum w_i (x_i - \mu)^2} \over {\sum w_i}}
$$
\afterdisplay
@end tex
@ifinfo
@example
\Hat\sigma^2 = (\sum w_i (x_i - \mu)^2) / (\sum w_i)
@end example
@end ifinfo
@end deftypefn

@deftypefn Statistics double gsl_stats_wsd_with_fixed_mean (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
The standard deviation is defined as the square root of the variance.
This function returns the square root of the corresponding variance
function above.
@end deftypefn

@deftypefn Statistics double gsl_stats_wabsdev (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function computes the weighted absolute deviation from the weighted
mean of @var{data}.  The absolute deviation from the mean is defined as,

@tex
\beforedisplay
$$
absdev = {{\sum w_i |x_i - \Hat\mu|} \over {\sum w_i}}
$$
\afterdisplay
@end tex
@ifinfo
@example
absdev = (\sum w_i |x_i - \Hat\mu|) / (\sum w_i)
@end example
@end ifinfo
@end deftypefn

@deftypefn Statistics double gsl_stats_wabsdev_m (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n}, double @var{wmean})
This function computes the absolute deviation of the weighted dataset
@var{data} about the given weighted mean @var{wmean}.
@end deftypefn

@deftypefn Statistics double gsl_stats_wskew (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function computes the weighted skewness of the dataset @var{data}.

@tex
\beforedisplay
$$
skew = {{\sum w_i ((x_i - xbar)/\sigma)^3} \over {\sum w_i}}
$$
\afterdisplay
@end tex
@ifinfo
@example
skew = (\sum w_i ((x_i - xbar)/\sigma)^3) / (\sum w_i)
@end example
@end ifinfo
@end deftypefn

@deftypefn Statistics double gsl_stats_wskew_m_sd (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n}, double @var{wmean}, double @var{wsd})
This function computes the weighted skewness of the dataset @var{data}
using the given values of the weighted mean and weighted standard
deviation, @var{wmean} and @var{wsd}.
@end deftypefn

@deftypefn Statistics double gsl_stats_wkurtosis (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function computes the weighted kurtosis of the dataset @var{data}.
@tex
\beforedisplay
$$
kurtosis = {{\sum w_i ((x_i - xbar)/sigma)^4} \over {\sum w_i}} - 3
$$
\afterdisplay
@end tex
@ifinfo
@example
kurtosis = ((\sum w_i ((x_i - xbar)/sigma)^4) / (\sum w_i)) - 3
@end example
@end ifinfo
@end deftypefn

@deftypefn Statistics double gsl_stats_wkurtosis_m_sd (const double @var{w}[], size_t @var{wstride}, const double @var{data}[], size_t @var{stride}, size_t @var{n}, double @var{wmean}, double @var{wsd})
This function computes the weighted kurtosis of the dataset @var{data}
using the given values of the weighted mean and weighted standard
deviation, @var{wmean} and @var{wsd}.
@end deftypefn

@node Maximum and Minimum values
@section Maximum and Minimum values

@deftypefn Statistics double gsl_stats_max (const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function returns the maximum value in @var{data}, a dataset of
length @var{n} with stride @var{stride}.  The maximum value is defined
as the value of the element @math{x_i} which satisfies @c{$x_i \ge x_j$}
@math{x_i >= x_j} for all @math{j}.

If you want instead to find the element with the largest absolute
magnitude you will need to apply @code{fabs} or @code{abs} to your data
before calling this function.
@end deftypefn

@deftypefn Statistics double gsl_stats_min (const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function returns the minimum value in @var{data}, a dataset of
length @var{n} with stride @var{stride}.  The minimum value is defined
as the value of the element @math{x_i} which satisfies @c{$x_i \le x_j$}
@math{x_i <= x_j} for all @math{j}.

If you want instead to find the element with the smallest absolute
magnitude you will need to apply @code{fabs} or @code{abs} to your data
before calling this function.
@end deftypefn

@deftypefn Statistics void gsl_stats_minmax (double * @var{min}, double * @var{max}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function finds both the minimum and maximum values @var{min},
@var{max} in @var{data} in a single pass.
@end deftypefn

@deftypefn Statistics size_t gsl_stats_max_index (const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function returns the index of the maximum value in @var{data}, a
dataset of length @var{n} with stride @var{stride}.  The maximum value is
defined as the value of the element @math{x_i} which satisfies 
@c{$x_i \ge x_j$}
@math{x_i >= x_j} for all @math{j}.  When there are several equal maximum
elements then the first one is chosen.
@end deftypefn

@deftypefn Statistics size_t gsl_stats_min_index (const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function returns the index of the minimum value in @var{data}, a
dataset of length @var{n} with stride @var{stride}.  The minimum value
is defined as the value of the element @math{x_i} which satisfies
@c{$x_i \ge x_j$}
@math{x_i >= x_j} for all @math{j}.  When there are several equal
minimum elements then the first one is chosen.
@end deftypefn

@deftypefn Statistics void gsl_stats_minmax_index (size_t * @var{min_index}, size_t * @var{max_index}, const double @var{data}[], size_t @var{stride}, size_t @var{n})
This function returns the indexes @var{min_index}, @var{max_index} of
the minimum and maximum values in @var{data} in a single pass.
@end deftypefn

@node Median and Percentiles
@section Median and Percentiles

The median and percentile functions described in this section operate on
sorted data.  For convenience we use @dfn{quantiles}, measured on a scale
of 0 to 1, instead of percentiles (which use a scale of 0 to 100).

@deftypefn Statistics double gsl_stats_median_from_sorted_data (const double @var{sorted_data}[], size_t @var{stride}, size_t @var{n})
This function returns the median value of @var{sorted_data}, a dataset
of length @var{n} with stride @var{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 @code{gsl_sort} should
always be used first.

When the dataset has an odd number of elements the median is the value
of element @math{(n-1)/2}.  When the dataset has an even number of
elements the median is the mean of the two nearest middle values,
elements @math{(n-1)/2} and @math{n/2}.  Since the algorithm for
computing the median involves interpolation this function always returns
a floating-point number, even for integer data types.
@end deftypefn

@deftypefn Statistics double gsl_stats_quantile_from_sorted_data (const double @var{sorted_data}[], size_t @var{stride}, size_t @var{n}, double @var{f})
This function returns a quantile value of @var{sorted_data}, a
double-precision array of length @var{n} with stride @var{stride}.  The
elements of the array must be in ascending numerical order.  The
quantile is determined by the @var{f}, a fraction between 0 and 1.  For
example, to compute the value of the 75th percentile @var{f} should have
the value 0.75.

There are no checks to see whether the data are sorted, so the function
@code{gsl_sort} should always be used first.

The quantile is found by interpolation, using the formula

@tex
\beforedisplay
$$
\hbox{quantile} = (1 - \delta) x_i + \delta x_{i+1}
$$
\afterdisplay
@end tex
@ifinfo
@example
quantile = (1 - \delta) x_i + \delta x_@{i+1@}
@end example
@end ifinfo

@noindent
where @math{i} is @code{floor}(@math{(n - 1)f}) and @math{\delta} is
@math{(n-1)f - i}.

Thus the minimum value of the array (@code{data[0*stride]}) is given by
@var{f} equal to zero, the maximum value (@code{data[(n-1)*stride]}) is
given by @var{f} equal to one and the median value is given by @var{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.
@end deftypefn


@comment @node Statistical tests
@comment @section Statistical tests

@comment FIXME, do more work on the statistical tests

@comment -@deftypefn Statistics double gsl_stats_ttest (const double @var{data1}[], double @var{data2}[], size_t @var{n1}, size_t @var{n2})
@comment -@deftypefnx Statistics double gsl_stats_int_ttest (const double @var{data1}[], double @var{data2}[], size_t @var{n1}, size_t @var{n2})

@comment The function @code{gsl_stats_ttest} computes the t-test statistic for
@comment the two arrays @var{data1}[] and @var{data2}[], of lengths @var{n1} and
@comment -@var{n2} respectively.

@comment The t-test statistic measures the difference between the means of two
@comment datasets.

@node Example statistical programs
@section Example statistical programs
Here is a basic example of how to use the statistical functions:

@example
#include <stdio.h>
#include <gsl/gsl_statistics.h>

int
main(void)
@{
  double data[5] = @{17.2, 18.1, 16.5, 18.3, 12.6@};
  double mean, variance, largest, smallest;

  mean     = gsl_stats_mean(data, 1, 5);
  variance = gsl_stats_variance(data, 1, 5);
  largest  = gsl_stats_max(data, 1, 5);
  smallest = gsl_stats_min(data, 1, 5);

  printf("The dataset is %g, %g, %g, %g, %g\n",
        data[0], data[1], data[2], data[3], data[4]);

  printf("The sample mean is %g\n", mean);
  printf("The estimated variance is %g\n", variance);
  printf("The largest value is %g\n", largest);
  printf("The smallest value is %g\n", smallest);
  return 0;
@}
@end example

The program should produce the following output,

@example
The dataset is 17.2, 18.1, 16.5, 18.3, 12.6
The sample mean is 16.54
The estimated variance is 4.2984
The largest value is 18.3
The smallest value is 12.6
@end example


Here is an example using sorted data,

@example
#include <stdio.h>
#include <gsl/gsl_sort.h>
#include <gsl/gsl_statistics.h>

int
main(void)
@{
  double data[5] = @{17.2, 18.1, 16.5, 18.3, 12.6@};
  double median, upperq, lowerq;

  printf("Original dataset:  %g, %g, %g, %g, %g\n",
        data[0], data[1], data[2], data[3], data[4]);

  gsl_sort (data, 1, 5);

  printf("Sorted dataset: %g, %g, %g, %g, %g\n",
        data[0], data[1], data[2], data[3], data[4]);

  median 
    = gsl_stats_median_from_sorted_data (data, 
                                         1, 5);

  upperq 
    = gsl_stats_quantile_from_sorted_data (data, 
                                           1, 5,
                                           0.75);
  lowerq 
    = gsl_stats_quantile_from_sorted_data (data, 
                                           1, 5,
                                           0.25);

  printf("The median is %g\n", median);
  printf("The upper quartile is %g\n", upperq);
  printf("The lower quartile is %g\n", lowerq);
  return 0;
@}
@end example

This program should produce the following output,

@example
Original dataset: 17.2, 18.1, 16.5, 18.3, 12.6
Sorted dataset: 12.6, 16.5, 17.2, 18.1, 18.3
The median is 17.2
The upper quartile is 18.1
The lower quartile is 16.5
@end example

@node Statistics References and Further Reading
@section References and Further Reading
@noindent
The standard reference for almost any topic in statistics is the
multi-volume @cite{Advanced Theory of Statistics} by Kendall and Stuart.

@itemize @asis
@item
Maurice Kendall, Alan Stuart, and J. Keith Ord.
@cite{The Advanced Theory of Statistics} (multiple volumes)
reprinted as @cite{Kendall's Advanced Theory of Statistics}.
Wiley, ISBN 047023380X.
@end itemize
@noindent
Many statistical concepts can be more easily understood by a Bayesian
approach.  The following book by Gelman, Carlin, Stern and Rubin gives a
comprehensive coverage of the subject.

@itemize @asis
@item
Andrew Gelman, John B. Carlin, Hal S. Stern, Donald B. Rubin.
@cite{Bayesian Data Analysis}.
Chapman & Hall, ISBN 0412039915.
@end itemize
@noindent
For physicists the Particle Data Group provides useful reviews of
Probability and Statistics in the "Mathematical Tools" section of its
Annual Review of Particle Physics. 

@itemize @asis
@item
@cite{Review of Particle Properties}
R.M. Barnett et al., Physical Review D54, 1 (1996)
@end itemize
@noindent
The Review of Particle Physics is available online at
@url{http://pdg.lbl.gov/}.