public class Variance extends AbstractStorelessUnivariateStatistic implements AggregatableStatistic<Variance>, WeightedEvaluation, Serializable
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.
Note that adding values using 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.
Modifier and Type  Field and Description 

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 and Description 

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 . 
Modifier and Type  Method and Description 

void 
aggregate(Variance other)
Aggregates the provided instance into this instance.

void 
clear()
Clears the internal state of the Statistic

Variance 
copy()
Returns a copy of the statistic with the same internal state.

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,
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() 
Variance 
withBiasCorrection(boolean biasCorrection)
Returns a new copy of this variance with the given bias correction
setting.

equals, hashCode, toString
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
aggregate, aggregate
evaluate
accept, incrementAll, incrementAll
evaluate
andThen
protected final SecondMoment moment
protected final 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.public Variance()
isBiasCorrected
property.public Variance(SecondMoment m2)
When this constructor is used, the statistic may only be
incremented via the moment, i.e., 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 copyNullArgumentException
 if original is nullpublic void increment(double d)
If all values are available, it is more accurate to use
UnivariateStatistic.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 void aggregate(Variance other)
This method can be used to combine statistics computed over partitions or subsamples  i.e., the value of this instance after this operation should be the same as if a single statistic would have been applied over the combined dataset.
aggregate
in interface AggregatableStatistic<Variance>
other
 the instance to aggregate into this instancepublic double evaluate(double[] values, int begin, int length) throws MathIllegalArgumentException
Double.NaN
if the designated subarray
is empty. Note that Double.NaN may also be returned if the input
includes NaN and / or infinite values.
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 StorelessUnivariateStatistic
evaluate
in interface UnivariateStatistic
evaluate
in interface MathArrays.Function
values
 the input arraybegin
 index of the first array element to includelength
 the number of elements to includeMathIllegalArgumentException
 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
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.
evaluate
in interface WeightedEvaluation
values
 the input arrayweights
 the weights arraybegin
 index of the first array element to includelength
 the number of elements to includeMathIllegalArgumentException
 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.
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 includeMathIllegalArgumentException
 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.
Does not change the internal state of the statistic.
values
 the input arraymean
 the precomputed mean valueMathIllegalArgumentException
 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 includeMathIllegalArgumentException
 if the parameters are not validpublic double evaluate(double[] values, double[] weights, double mean) throws MathIllegalArgumentException
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 valueMathIllegalArgumentException
 if the parameters are not validpublic boolean isBiasCorrected()
public Variance withBiasCorrection(boolean biasCorrection)
biasCorrection
 The bias correction flag to set.public Variance copy()
copy
in interface StorelessUnivariateStatistic
copy
in interface UnivariateStatistic
copy
in class AbstractStorelessUnivariateStatistic
Copyright © 20162022 CS GROUP. All rights reserved.