commonSense.stat.basic
Class Variances

java.lang.Object
  extended byorg.apache.commons.math.stat.univariate.AbstractUnivariateStatistic
      extended byorg.apache.commons.math.stat.univariate.AbstractStorelessUnivariateStatistic
          extended bycommonSense.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


RealJ version 3.5 2001. www.realj.com