diff --git a/statistics/mean-variance.lisp b/statistics/mean-variance.lisp index fd030fcbcb8fd4655e1c20a8700ebfb726d9fe39..09bfeb126f649422e8f6ce6042513068f0a08be1 100644 --- a/statistics/mean-variance.lisp +++ b/statistics/mean-variance.lisp @@ -1,21 +1,13 @@ ;; Mean, standard deviation, and variance ;; Liam Healy, Sat Dec 2 2006 - 22:15 -;; Time-stamp: <2008-08-17 12:06:30EDT mean-variance.lisp> +;; Time-stamp: <2008-08-17 19:00:54EDT mean-variance.lisp> ;; $Id$ (in-package :gsl) -;;; To do: stride other than 1 when that information is availble from +;;; To do: stride other than 1 when that information is available from ;;; the vector. -(defmacro defmfun-stats (&rest args) - "A defmfun for stats of double, single, and fixnum." - (defmfun-all 'vector '(double-float single-float fixnum) args "stats")) - -(defmacro defmfun-stats-ds (&rest args) - "A defmfun for stats of double and single." - (defmfun-all 'vector '(double-float single-float) args "stats")) - ;;;;**************************************************************************** ;;;; Mean and weighted mean ;;;;**************************************************************************** @@ -69,224 +61,126 @@ If the mean value is known, it may be supplied which will use more efficient routines to compute the variance.") -(defgeneric variance-nom (vector) - (:documentation ; FDL - "The estimated, or sample, variance of data. 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 #'mean. If - you have already computed the mean then you can pass it directly to - #'variance-m.")) - -(defmfun-stats variance-nom ((vector vector)) - "gsl_stats_variance" - (((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size)) - :index variance - :export nil - :c-return :double) - -(defgeneric variance-m (vector mean) - (:documentation ; FDL - "Compute the variance with the mean known to - avoid its recomputation.")) - -(defmfun-stats variance-m ((vector vector) mean) - "gsl_stats_variance_m" - (((gsl-array vector) :pointer) (1 :int) - ((dim0 vector) size) (mean :double)) - :index variance - :export nil - :c-return :double) - -(export 'variance) -(defun-optionals variance (data &optional mean) - -nom -m - ;; FDL - "The estimated, or sample, variance of data. 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. 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.") - -;;;;**************************************************************************** -;;;; Weighted variance -;;;;**************************************************************************** - -(defgeneric weighted-variance-nom (vector weights) - (:documentation ; FDL - "Compute the weighted variance with the mean unknown.")) - -(defmfun-stats-ds weighted-variance-nom ((vector vector) weights) - "gsl_stats_wvariance" - (((gsl-array weights) :pointer) (1 :int) - ((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size)) - :index weighted-variance - :export nil - :c-return :double) - -(defgeneric weighted-variance-m (vector weights mean) - (:documentation ; FDL - "Compute the weighted variance with the mean known to - avoid its recomputation.")) - -(defmfun-stats-ds weighted-variance-m ((vector vector) weights mean) - "gsl_stats_wvariance_m" - (((gsl-array weights) :pointer) (1 :int) - ((gsl-array vector) :pointer) (1 :int) - ((dim0 vector) size) (mean :double)) - :index variance - :export nil - :c-return :double) - -(export 'weighted-variance) -(defun-optionals weighted-variance (data weights &optional mean) - -nom -m - ;; FDL - "The estimated variance using weights - The estimated variance of a weighted dataset is defined as +(defmfun weighted-variance ((vector vector) (weights vector) &optional mean) + (("gsl_stats" :type "_wvariance") + ("gsl_stats" :type "_wvariance_m")) + ((((c-pointer weights) :pointer) (1 :int) + ((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet)) + (((c-pointer weights) :pointer) (1 :int) + ((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double))) + :definition :generic + :element-types :float + :c-return :double + :documentation ; FDL + "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.") + familiar 1/(N-1) factor when there are N equal non-zero weights. + If the mean value is known, it may be supplied which will use more + efficient routines to compute the variance.") ;;;;**************************************************************************** ;;;; Standard deviation ;;;;**************************************************************************** -(defgeneric standard-deviation-nom (vector) - (:documentation ; FDL - "The standard deviation, square root of the variance.")) - -(defmfun-stats standard-deviation-nom ((vector vector)) - "gsl_stats_sd" - (((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size)) - :index standard-deviation - :export nil - :c-return :double) - -(defgeneric standard-deviation-m (vector mean) - (:documentation ; FDL - "The standard deviation with the mean known to - avoid its recomputation.")) - -(defmfun-stats standard-deviation-m ((vector vector) mean) - "gsl_stats_sd_m" - (((gsl-array vector) :pointer) (1 :int) - ((dim0 vector) size) (mean :double)) - :c-return :double) - -(export 'standard-deviation) -(defun-optionals standard-deviation (data &optional mean) - -nom -m - ;; FDL - "The standard deviation, square root of the variance.") - -;;;;**************************************************************************** -;;;; Weighted standard deviation -;;;;**************************************************************************** - -(defgeneric weighted-standard-deviation-nom (vector weights)) - -(defmfun-stats-ds weighted-standard-deviation-nom - ((vector vector) weights) - "gsl_stats_wsd" - (((gsl-array weights) :pointer) (1 :int) - ((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size)) - :index weighted-standard-deviation - :export nil - :c-return :double) - -(defgeneric weighted-standard-deviation-m (vector weights mean)) - -(defmfun-stats-ds weighted-standard-deviation-m - ((vector vector) weights mean) - "gsl_stats_wsd_m" - (((gsl-array weights) :pointer) (1 :int) - ((gsl-array vector) :pointer) (1 :int) - ((dim0 vector) size) (mean :double)) - :c-return :double) +(defmfun standard-deviation ((vector vector) &optional mean) + (("gsl_stats" :type "_sd") + ("gsl_stats" :type "_sd_m")) + ((((c-pointer vector) :pointer) (1 :int) ((dim0 vector) sizet)) + (((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double))) + :definition :generic + :element-types :no-complex + :c-return :double + :documentation ; FDL + "The standard deviation, square root of the variance. + If the mean value is known, it may be supplied which will use more + efficient routines to compute the variance.") -(export 'weighted-standard-deviation) -(defun-optionals weighted-standard-deviation (data weights &optional mean) - -nom -m - ;; FDL - "The standard deviation, square root of the variance.") +(defmfun weighted-standard-deviation ((vector vector) (weights vector) &optional mean) + (("gsl_stats" :type "_wsd") + ("gsl_stats" :type "_wsd_m")) + ((((c-pointer weights) :pointer) (1 :int) + ((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet)) + (((c-pointer weights) :pointer) (1 :int) + ((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double))) + :definition :generic + :element-types :float + :c-return :double + :documentation ; FDL + "The weighted standard deviation, square root of the variance. + If the mean value is known, it may be supplied which will use more + efficient routines to compute the variance.") ;;;;**************************************************************************** -;;;; Variance with fixed mean +;;;; With fixed mean ;;;;**************************************************************************** -(defgeneric variance-with-fixed-mean (vector mean) - (:documentation ; FDL - "An unbiased estimate of the variance of +(defmfun variance-with-fixed-mean ((vector vector) mean) + ("gsl_stats" :type "_variance_with_fixed_mean") + (((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double)) + :definition :generic + :element-types :no-complex + :c-return :double + :documentation ; FDL + "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.")) - -(defmfun-stats variance-with-fixed-mean ((vector vector) mean) - "gsl_stats_variance_with_fixed_mean" - (((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size) - (mean :double)) - :c-return :double) + \Hat\sigma^2 = (1/N) \sum (x_i - \mu)^2.") -(defgeneric standard-deviation-with-fixed-mean (vector mean) - (:documentation ; FDL +(defmfun standard-deviation-with-fixed-mean ((vector vector) mean) + ("gsl_stats" :type "_sd_with_fixed_mean") + (((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double)) + :definition :generic + :element-types :no-complex + :c-return :double + :documentation ; FDL "The standard deviation of data for a fixed population mean. The result is the square root of the - corresponding variance function.")) - -(defmfun-stats standard-deviation-with-fixed-mean - ((vector vector) mean) - "gsl_stats_sd_with_fixed_mean" - (((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size) - (mean :double)) - :c-return :double) + corresponding variance function.") ;;;;**************************************************************************** -;;;; Weighted variance with fixed mean +;;;; Weighted with fixed mean ;;;;**************************************************************************** -(defgeneric weighted-variance-with-fixed-mean (vector weights mean) - (:documentation ; FDL - "An unbiased estimate of the variance of weighted +(defmfun weighted-variance-with-fixed-mean + ((vector vector) (weights vector) mean) + ("gsl_stats" :type "_wvariance_with_fixed_mean") + (((c-pointer weights) :pointer) (1 :int) + ((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double)) + :definition :generic + :element-types :float + :c-return :double + :documentation ; FDL + "An unbiased estimate of the variance of weighted dataset when the population 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).")) + \Hat\sigma^2 = (\sum w_i (x_i - \mu)^2) / (\sum w_i).") -(defmfun-stats-ds weighted-variance-with-fixed-mean - ((vector vector) weights mean) - "gsl_stats_wvariance_with_fixed_mean" - (((gsl-array weights) :pointer) (1 :int) - ((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size) - (mean :double)) - :c-return :double) - -(defgeneric weighted-standard-deviation-with-fixed-mean - (vector weights mean) - (:documentation ; FDL - "The square root of the corresponding variance - function #'weighted-variance-with-fixed-mean.")) - -(defmfun-stats-ds weighted-standard-deviation-with-fixed-mean - ((vector vector) weights mean) - "gsl_stats_wsd_with_fixed_mean" - (((gsl-array weights) :pointer) (1 :int) - ((gsl-array vector) :pointer) (1 :int) ((dim0 vector) size) - (mean :double)) - :c-return :double) +(defmfun weighted-standard-deviation-with-fixed-mean + ((vector vector) (weights vector) mean) + ("gsl_stats" :type "_wsd_with_fixed_mean") + (((c-pointer weights) :pointer) (1 :int) + ((c-pointer vector) :pointer) (1 :int) + ((dim0 vector) sizet) (mean :double)) + :definition :generic + :element-types :float + :c-return :double + :documentation ; FDL + "The square root of the corresponding variance + function #'weighted-variance-with-fixed-mean.") ;;;;**************************************************************************** ;;;; Examples and unit test @@ -318,7 +212,6 @@ (standard-deviation vec mean) (variance-with-fixed-mean vec 4.0d0) (standard-deviation-with-fixed-mean vec 4.0d0))))) -|# (LISP-UNIT:DEFINE-TEST MEAN-VARIANCE (LISP-UNIT::ASSERT-NUMERICAL-EQUAL @@ -357,3 +250,4 @@ (VARIANCE-WITH-FIXED-MEAN VEC 4.0d0) (STANDARD-DEVIATION-WITH-FIXED-MEAN VEC 4.0d0))))))) +|#