commonSense.stat.basic
Class Variances

java.lang.Object
  org.apache.commons.math.stat.univariate.AbstractUnivariateStatistic
      org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatistic
          commonSense.stat.basic.Variances

All Implemented Interfaces:

java.io.Serializable, org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic, org.apache.commons.math.stat.univariate.UnivariateStatistic, VarianceTypes

public class Variances

extends org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatistic

implements java.io.Serializable, VarianceTypes

Computes the variance for a specific type VarianceTypes. Uses the definitional formula:

variance = sum((x_i - mean)^2) / (n - type)

where mean is the Mean and n is the number of sample observations. When the type is VarianceTypes.SAMPLE it calculates the standard bias free sample variance with corresponds with n - 1. When the type is VarianceTypes.POPULATION, n is left unchanged. In general, the number provided for type is subtracted equivalent to n - type.

The definitional formula does not have good numerical properties, so this implementation uses updating formulas based on West's algorithm as described in Chan, T. F. andJ. G. Lewis 1979, Communications of the ACM, vol. 22 no. 9, pp. 526-531..

Note that this implementation is not synchronized. If multiple threads access an instance of this class concurrently, and at least one of the threads invokes the increment() or clear() method, it must be synchronized externally.

Version:

Date: 1 September 2004

See Also:

Serialized Form

Field Summary

protected boolean	incMoment Boolean test to determine if this Variance should also increment the second moment, this evaluates to false when this Variance is constructed with an external SecondMoment as a parameter.
protected SecondMoment	moment SecondMoment is used in incremental calculation of Variance

Fields inherited from interface commonSense.stat.VarianceTypes

POPULATION, SAMPLE

Constructor Summary

Variances()
Constructs a Variance.

Variances(SecondMoment m2)
Constructs a Variance based on an external second moment.

Method Summary

void	clear()
double	evaluate(double[] values) Returns the variance of the entries in the input array, or Double.NaN if the array is empty.
double	evaluate(double[] values, double mean) Returns the variance of the entries in the input array, using the precomputed mean value.
double	evaluate(double[] values, double mean, int type) Returns the variance of the entries in the input array, using the precomputed mean value.
double	evaluate(double[] values, double mean, int begin, int length) Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value.
double	evaluate(double[] values, double mean, int begin, int length, int type) Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value.
double	evaluate(double[] values, int type) Returns the variance of the entries in the input array, or Double.NaN if the array is empty.
double	evaluate(double[] values, int begin, int length) Returns the variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
double	evaluate(double[] values, int begin, int length, int type) Returns the variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.
long	getN()
double	getResult() Gives back the sample variance.
double	getResult(int type) Gives back the variance of the specified type.
void	increment(double d)

Methods inherited from class org.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatistic

equals, hashCode, incrementAll, incrementAll

Methods inherited from class org.apache.commons.math.stat.univariate.AbstractUnivariateStatistic

test

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Detail

moment

protected SecondMoment moment

SecondMoment is used in incremental calculation of Variance

incMoment

protected boolean incMoment

Boolean test to determine if this Variance should also increment the second moment, this evaluates to false when this Variance is constructed with an external SecondMoment as a parameter.

Constructor Detail

Variances

public Variances()

Constructs a Variance.

Variances

public Variances(SecondMoment m2)

Constructs a Variance based on an external second moment.

Parameters:

m2 - the SecondMoment (Thrid or Fourth moments work here as well.)

Method Detail

increment

public void increment(double d)

Specified by:

increment in interface org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic

See Also:

StorelessUnivariateStatistic.increment(double)

getResult

public double getResult(int type)

Gives back the variance of the specified type. When the type is VarianceTypes.SAMPLE it calculates the standard bias free sample variance with corresponds with n = N - 1 in which N is the number of rows in the matrix. When the type is VarianceTypes.POPULATION, N is left unchanged (n = N). In general, the number provided for type is subtracted equivalent to n = N - type.

Parameters:

type - The type of variance that should be calculated, be it sample or population (co-)variances.

Returns:

The variance of the specified type, or NaN when the number of observations is less that the number specified in type.

See Also:

VarianceTypes, StorelessUnivariateStatistic.getResult()

getResult

public double getResult()

Gives back the sample variance.

Specified by:

getResult in interface org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic

Returns:

The sample variance of the specified type, or NaN when the number of observations is zero.

See Also:

VarianceTypes, StorelessUnivariateStatistic.getResult()

getN

public long getN()

Specified by:

getN in interface org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic

See Also:

StorelessUnivariateStatistic.getN()

clear

public void clear()

Specified by:

clear in interface org.apache.commons.math.stat.univariate.StorelessUnivariateStatistic

See Also:

StorelessUnivariateStatistic.clear()

evaluate

public double evaluate(double[] values)

Returns the variance of the entries in the input array, or Double.NaN if the array is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Throws IllegalArgumentException if the array is null.

Does not change the internal state of the statistic.

Specified by:

evaluate in interface org.apache.commons.math.stat.univariate.UnivariateStatistic

Parameters:

values - the input array

Returns:

the variance of the values or Double.NaN if length = 0

Throws:

java.lang.IllegalArgumentException - if the array is null

evaluate

public double evaluate(double[] values,
                       int begin,
                       int length)

Returns the variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Does not change the internal state of the statistic.

Throws IllegalArgumentException if the array is null.

Specified by:

evaluate in interface org.apache.commons.math.stat.univariate.UnivariateStatistic

Parameters:

values - the input array

begin - index of the first array element to include

length - the number of elements to include

Returns:

the variance of the values or Double.NaN if length = 0

Throws:

java.lang.IllegalArgumentException - if the array is null or the array index parameters are not valid

evaluate

public double evaluate(double[] values,
                       double mean,
                       int begin,
                       int length)

Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns Double.NaN if the designated subarray is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Throws IllegalArgumentException if the array is null.

Does not change the internal state of the statistic.

Parameters:

values - the input array

mean - the precomputed mean value

begin - index of the first array element to include

length - the number of elements to include

Returns:

the variance of the values or Double.NaN if length = 0

Throws:

java.lang.IllegalArgumentException - if the array is null or the array index parameters are not valid

evaluate

public double evaluate(double[] values,
                       double mean)

Returns the variance of the entries in the input array, using the precomputed mean value. Returns Double.NaN if the array is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Throws IllegalArgumentException if the array is null.

Does not change the internal state of the statistic.

Parameters:

values - the input array

mean - the precomputed mean value

Returns:

the variance of the values or Double.NaN if the array is empty

Throws:

java.lang.IllegalArgumentException - if the array is null

evaluate

public double evaluate(double[] values,
                       int type)

Returns the variance of the entries in the input array, or Double.NaN if the array is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Throws IllegalArgumentException if the array is null.

Does not change the internal state of the statistic.

Parameters:

values - the input array

type - The type of variance that should be calculated, be it the sample or population variance.

Returns:

the variance of the values or Double.NaN if length = 0

Throws:

java.lang.IllegalArgumentException - if the array is null

See Also:

VarianceTypes

evaluate

public double evaluate(double[] values,
                       int begin,
                       int length,
                       int type)

Returns the variance of the entries in the specified portion of the input array, or Double.NaN if the designated subarray is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Does not change the internal state of the statistic.

Throws IllegalArgumentException if the array is null.

Parameters:

values - the input array

begin - index of the first array element to include

length - the number of elements to include

type - The type of variance that should be calculated, be it the sample or population variance.

Returns:

the variance of the values or Double.NaN if length = 0

Throws:

java.lang.IllegalArgumentException - if the array is null or the array index parameters are not valid

See Also:

VarianceTypes

evaluate

public double evaluate(double[] values,
                       double mean,
                       int begin,
                       int length,
                       int type)

Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns Double.NaN if the designated subarray is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Throws IllegalArgumentException if the array is null.

Does not change the internal state of the statistic.

type should be set to VarianceTypes.SAMPLE when the precomputed mean is based on the same sample, but to VarianceTypes.POPULATION when the precomputed mean is based on the different sample.

Parameters:

values - the input array

mean - the precomputed mean value

begin - index of the first array element to include

length - the number of elements to include

type - The type of variance that should be calculated, be it the sample or population variance.

Returns:

the variance of the values or Double.NaN if length = 0

Throws:

java.lang.IllegalArgumentException - if the array is null or the array index parameters are not valid

See Also:

VarianceTypes

evaluate

public double evaluate(double[] values,
                       double mean,
                       int type)

Returns the variance of the entries in the input array, using the precomputed mean value. Returns Double.NaN if the array is empty.

See Variances for details on the computing algorithm.

Returns 0 for a single-value (i.e. length = 1) sample.

Throws IllegalArgumentException if the array is null.

Does not change the internal state of the statistic.

type should be set to VarianceTypes.SAMPLE when the precomputed mean is based on the same sample, but to VarianceTypes.POPULATION when the precomputed mean is based on the different sample.

Parameters:

values - the input array

mean - the precomputed mean value

type - The type of variance that should be calculated, be it the sample or population variance.

Returns:

the variance of the values or Double.NaN if the array is empty

Throws:

java.lang.IllegalArgumentException - if the array is null

See Also:

VarianceTypes