

PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic org.apache.commons.math3.stat.descriptive.moment.Variance
public class Variance
Computes the variance of the available values. By default, the unbiased "sample variance" definitional formula is used:
variance = sum((x_i  mean)^2) / (n  1)
where mean is the Mean
and n
is the number
of sample observations.
The definitional formula does not have good numerical properties, so this implementation does not compute the statistic using the definitional formula.
getResult
method computes the variance using
updating formulas based on West's algorithm, as described in
Chan, T. F. and
J. G. Lewis 1979, Communications of the ACM,
vol. 22 no. 9, pp. 526531.evaluate
methods leverage the fact that they have the
full array of values in memory to execute a twopass algorithm.
Specifically, these methods use the "corrected twopass algorithm" from
Chan, Golub, Levesque, Algorithms for Computing the Sample Variance,
American Statistician, vol. 37, no. 3 (1983) pp. 242247.increment
or
incrementAll
and then executing getResult
will
sometimes give a different, less accurate, result than executing
evaluate
with the full array of values. The former approach
should only be used when the full array of values is not available.
The "population variance" ( sum((x_i  mean)^2) / n ) can also
be computed using this statistic. The isBiasCorrected
property determines whether the "population" or "sample" value is
returned by the evaluate
and getResult
methods.
To compute population variances, set this property to false.
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.
Field Summary  

protected boolean 
incMoment
Whether or not increment(double) should increment
the internal second moment. 
protected SecondMoment 
moment
SecondMoment is used in incremental calculation of Variance 
Constructor Summary  

Variance()
Constructs a Variance with default (true) isBiasCorrected
property. 

Variance(boolean isBiasCorrected)
Constructs a Variance with the specified isBiasCorrected
property 

Variance(boolean isBiasCorrected,
SecondMoment m2)
Constructs a Variance with the specified isBiasCorrected
property and the supplied external second moment. 

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

Variance(Variance original)
Copy constructor, creates a new Variance identical
to the original 
Method Summary  

void 
clear()
Clears the internal state of the Statistic 
Variance 
copy()
Returns a copy of the statistic with the same internal state. 
static void 
copy(Variance source,
Variance dest)
Copies source to dest. 
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[] weights)
Returns the weighted variance of the entries in the the input array. 
double 
evaluate(double[] values,
double[] weights,
double mean)
Returns the weighted variance of the values in the input array, using the precomputed weighted mean value. 
double 
evaluate(double[] values,
double[] weights,
double mean,
int begin,
int length)
Returns the weighted variance of the entries in the specified portion of the input array, using the precomputed weighted mean value. 
double 
evaluate(double[] values,
double[] weights,
int begin,
int length)
Returns the weighted 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,
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,
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. 
long 
getN()
Returns the number of values that have been added. 
double 
getResult()
Returns the current value of the Statistic. 
void 
increment(double d)
Updates the internal state of the statistic to reflect the addition of the new value. 
boolean 
isBiasCorrected()

void 
setBiasCorrected(boolean biasCorrected)

Methods inherited from class org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic 

equals, hashCode, incrementAll, incrementAll 
Methods inherited from class org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic 

evaluate, getData, getDataRef, setData, setData, test, test, test, test 
Methods inherited from class java.lang.Object 

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

protected SecondMoment moment
protected boolean incMoment
increment(double)
should increment
the internal second moment. When a Variance is constructed with an
external SecondMoment as a constructor parameter, this property is
set to false and increments must be applied to the second moment
directly.
Constructor Detail 

public Variance()
isBiasCorrected
property.
public Variance(SecondMoment m2)
increment(double)
does nothing; whereas m2.increment(value)
increments
both m2
and the Variance instance constructed from it.
m2
 the SecondMoment (Third or Fourth moments work
here as well.)public Variance(boolean isBiasCorrected)
isBiasCorrected
property
isBiasCorrected
 setting for bias correction  true means
bias will be corrected and is equivalent to using the argumentless
constructorpublic Variance(boolean isBiasCorrected, SecondMoment m2)
isBiasCorrected
property and the supplied external second moment.
isBiasCorrected
 setting for bias correction  true means
bias will be correctedm2
 the SecondMoment (Third or Fourth moments work
here as well.)public Variance(Variance original) throws NullArgumentException
Variance
identical
to the original
original
 the Variance
instance to copy
NullArgumentException
 if original is nullMethod Detail 

public void increment(double d)
If all values are available, it is more accurate to use
evaluate(double[])
rather than adding values one at a time
using this method and then executing getResult()
, since
evaluate
leverages the fact that is has the full
list of values together to execute a twopass algorithm.
See Variance
.
Note also that when Variance(SecondMoment)
is used to
create a Variance, this method does nothing. In that case, the
SecondMoment should be incremented directly.
increment
in interface StorelessUnivariateStatistic
increment
in class AbstractStorelessUnivariateStatistic
d
 the new value.public double getResult()
getResult
in interface StorelessUnivariateStatistic
getResult
in class AbstractStorelessUnivariateStatistic
Double.NaN
if it
has been cleared or just instantiated.public long getN()
getN
in interface StorelessUnivariateStatistic
public void clear()
clear
in interface StorelessUnivariateStatistic
clear
in class AbstractStorelessUnivariateStatistic
public double evaluate(double[] values) throws MathIllegalArgumentException
Double.NaN
if the array is empty.
See Variance
for details on the computing algorithm.
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws MathIllegalArgumentException
if the array is null.
Does not change the internal state of the statistic.
evaluate
in interface UnivariateStatistic
evaluate
in interface MathArrays.Function
evaluate
in class AbstractStorelessUnivariateStatistic
values
 the input array
MathIllegalArgumentException
 if the array is nullUnivariateStatistic.evaluate(double[])
public double evaluate(double[] values, int begin, int length) throws MathIllegalArgumentException
Double.NaN
if the designated subarray
is empty.
See Variance
for details on the computing algorithm.
Returns 0 for a singlevalue (i.e. length = 1) sample.
Does not change the internal state of the statistic.
Throws MathIllegalArgumentException
if the array is null.
evaluate
in interface UnivariateStatistic
evaluate
in interface MathArrays.Function
evaluate
in class AbstractStorelessUnivariateStatistic
values
 the input arraybegin
 index of the first array element to includelength
 the number of elements to include
MathIllegalArgumentException
 if the array is null or the array index
parameters are not validUnivariateStatistic.evaluate(double[], int, int)
public double evaluate(double[] values, double[] weights, int begin, int length) throws MathIllegalArgumentException
Returns the weighted variance of the entries in the specified portion of
the input array, or Double.NaN
if the designated subarray
is empty.
Uses the formula
Σ(weights[i]*(values[i]  weightedMean)^{2})/(Σ(weights[i])  1)where weightedMean is the weighted mean
This formula will not return the same result as the unweighted variance when all weights are equal, unless all weights are equal to 1. The formula assumes that weights are to be treated as "expansion values," as will be the case if for example the weights represent frequency counts. To normalize weights so that the denominator in the variance computation equals the length of the input vector minus one, use
evaluate(values, MathArrays.normalizeArray(weights, values.length));
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws IllegalArgumentException
if any of the following are true:
Does not change the internal state of the statistic.
Throws MathIllegalArgumentException
if either array is null.
evaluate
in interface WeightedEvaluation
values
 the input arrayweights
 the weights arraybegin
 index of the first array element to includelength
 the number of elements to include
MathIllegalArgumentException
 if the parameters are not validpublic double evaluate(double[] values, double[] weights) throws MathIllegalArgumentException
Returns the weighted variance of the entries in the the input array.
Uses the formula
Σ(weights[i]*(values[i]  weightedMean)^{2})/(Σ(weights[i])  1)where weightedMean is the weighted mean
This formula will not return the same result as the unweighted variance when all weights are equal, unless all weights are equal to 1. The formula assumes that weights are to be treated as "expansion values," as will be the case if for example the weights represent frequency counts. To normalize weights so that the denominator in the variance computation equals the length of the input vector minus one, use
evaluate(values, MathArrays.normalizeArray(weights, values.length));
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws MathIllegalArgumentException
if any of the following are true:
Does not change the internal state of the statistic.
Throws MathIllegalArgumentException
if either array is null.
evaluate
in interface WeightedEvaluation
values
 the input arrayweights
 the weights array
MathIllegalArgumentException
 if the parameters are not validpublic double evaluate(double[] values, double mean, int begin, int length) throws MathIllegalArgumentException
Double.NaN
if the designated subarray is empty.
See Variance
for details on the computing algorithm.
The formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws MathIllegalArgumentException
if the array is null.
Does not change the internal state of the statistic.
values
 the input arraymean
 the precomputed mean valuebegin
 index of the first array element to includelength
 the number of elements to include
MathIllegalArgumentException
 if the array is null or the array index
parameters are not validpublic double evaluate(double[] values, double mean) throws MathIllegalArgumentException
Double.NaN
if the array
is empty.
See Variance
for details on the computing algorithm.
If isBiasCorrected
is true
the formula used
assumes that the supplied mean value is the arithmetic mean of the
sample data, not a known population parameter. If the mean is a known
population parameter, or if the "population" version of the variance is
desired, set isBiasCorrected
to false
before
invoking this method.
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws MathIllegalArgumentException
if the array is null.
Does not change the internal state of the statistic.
values
 the input arraymean
 the precomputed mean value
MathIllegalArgumentException
 if the array is nullpublic double evaluate(double[] values, double[] weights, double mean, int begin, int length) throws MathIllegalArgumentException
Double.NaN
if the designated subarray is empty.
Uses the formula
Σ(weights[i]*(values[i]  mean)^{2})/(Σ(weights[i])  1)
The formula used assumes that the supplied mean value is the weighted arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.
This formula will not return the same result as the unweighted variance when all weights are equal, unless all weights are equal to 1. The formula assumes that weights are to be treated as "expansion values," as will be the case if for example the weights represent frequency counts. To normalize weights so that the denominator in the variance computation equals the length of the input vector minus one, use
evaluate(values, MathArrays.normalizeArray(weights, values.length), mean);
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws MathIllegalArgumentException
if any of the following are true:
Does not change the internal state of the statistic.
values
 the input arrayweights
 the weights arraymean
 the precomputed weighted mean valuebegin
 index of the first array element to includelength
 the number of elements to include
MathIllegalArgumentException
 if the parameters are not validpublic double evaluate(double[] values, double[] weights, double mean) throws MathIllegalArgumentException
Returns the weighted variance of the values in the input array, using the precomputed weighted mean value.
Uses the formula
Σ(weights[i]*(values[i]  mean)^{2})/(Σ(weights[i])  1)
The formula used assumes that the supplied mean value is the weighted arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.
This formula will not return the same result as the unweighted variance when all weights are equal, unless all weights are equal to 1. The formula assumes that weights are to be treated as "expansion values," as will be the case if for example the weights represent frequency counts. To normalize weights so that the denominator in the variance computation equals the length of the input vector minus one, use
evaluate(values, MathArrays.normalizeArray(weights, values.length), mean);
Returns 0 for a singlevalue (i.e. length = 1) sample.
Throws MathIllegalArgumentException
if any of the following are true:
Does not change the internal state of the statistic.
values
 the input arrayweights
 the weights arraymean
 the precomputed weighted mean value
MathIllegalArgumentException
 if the parameters are not validpublic boolean isBiasCorrected()
public void setBiasCorrected(boolean biasCorrected)
biasCorrected
 The isBiasCorrected to set.public Variance copy()
copy
in interface StorelessUnivariateStatistic
copy
in interface UnivariateStatistic
copy
in class AbstractStorelessUnivariateStatistic
public static void copy(Variance source, Variance dest) throws NullArgumentException
Neither source nor dest can be null.
source
 Variance to copydest
 Variance to copy to
NullArgumentException
 if either source or dest is null


PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 