Class Variance
- All Implemented Interfaces:
DoubleConsumer
,DoubleSupplier
,IntSupplier
,LongSupplier
,DoubleStatistic
,StatisticAccumulator<Variance>
,StatisticResult
\[ \tfrac{1}{n-1} \sum_{i=1}^n (x_i-\overline{x})^2 \]
where \( \overline{x} \) is the sample mean, and \( n \) is the number of samples.
- The result is
NaN
if no values are added. - The result is
NaN
if any of the values isNaN
or infinite. - The result is
NaN
if the sum of the squared deviations from the mean is infinite. - The result is zero if there is one finite value in the data set.
The use of the term \( n − 1 \) is called Bessel's correction. This is an unbiased
estimator of the variance of a hypothetical infinite population. If the
biased
option is enabled the normalisation factor is
changed to \( \frac{1}{n} \) for a biased estimator of the sample variance.
The accept(double)
method uses a recursive updating algorithm based on West's
algorithm (see Chan and Lewis (1979)).
The of(double...)
method uses the corrected two-pass algorithm from
Chan et al, (1983).
Note that adding values using accept
and then executing
getAsDouble
will
sometimes give a different, less accurate, result than executing
of
with the full array of values. The former approach
should only be used when the full array of values is not available.
Supports up to 263 (exclusive) observations. This implementation does not check for overflow of the count.
This class is designed to work with (though does not require) streams.
Note that this instance is not synchronized. If
multiple threads access an instance of this class concurrently, and at least
one of the threads invokes the accept
or
combine
method, it must be synchronized externally.
However, it is safe to use accept
and combine
as accumulator
and combiner
functions of
Collector
on a parallel stream,
because the parallel instance of Stream.collect()
provides the necessary partitioning, isolation, and merging of results for
safe and efficient parallel execution.
References:
- Chan and Lewis (1979) Computing standard deviations: accuracy. Communications of the ACM, 22, 526-531. doi: 10.1145/359146.359152
- Chan, Golub and Levesque (1983) Algorithms for Computing the Sample Variance: Analysis and Recommendations. American Statistician, 37, 242-247. doi: 10.2307/2683386
- Since:
- 1.1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate boolean
Flag to control if the statistic is biased, or should use a bias correction.private final SumOfSquaredDeviations
An instance ofSumOfSquaredDeviations
, which is used to compute the variance. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Variance()
Create an instance.(package private)
Creates an instance with the sum of squared deviations from the mean. -
Method Summary
Modifier and TypeMethodDescriptionvoid
accept
(double value) Updates the state of the statistic to reflect the addition ofvalue
.Combines the state of theother
statistic into this one.static Variance
create()
Creates an instance.double
Gets the variance of all input values.static Variance
of
(double... values) Returns an instance populated using the inputvalues
.setBiased
(boolean v) Sets the value of the biased flag.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.util.function.DoubleConsumer
andThen
Methods inherited from interface org.apache.commons.statistics.descriptive.StatisticResult
getAsBigInteger, getAsInt, getAsLong
-
Field Details
-
ss
An instance ofSumOfSquaredDeviations
, which is used to compute the variance. -
biased
private boolean biasedFlag to control if the statistic is biased, or should use a bias correction.
-
-
Constructor Details
-
Variance
private Variance()Create an instance. -
Variance
Variance(SumOfSquaredDeviations ss) Creates an instance with the sum of squared deviations from the mean.- Parameters:
ss
- Sum of squared deviations.
-
-
Method Details
-
create
Creates an instance.The initial result is
NaN
.- Returns:
Variance
instance.
-
of
Returns an instance populated using the inputvalues
.Note:
Variance
computed usingaccept
may be different from this variance.See
Variance
for details on the computing algorithm.- Parameters:
values
- Values.- Returns:
Variance
instance.
-
accept
public void accept(double value) Updates the state of the statistic to reflect the addition ofvalue
.- Specified by:
accept
in interfaceDoubleConsumer
- Parameters:
value
- Value.
-
getAsDouble
public double getAsDouble()Gets the variance of all input values.When no values have been added, the result is
NaN
.- Specified by:
getAsDouble
in interfaceDoubleSupplier
- Returns:
- variance of all values.
-
combine
Description copied from interface:StatisticAccumulator
Combines the state of theother
statistic into this one.- Specified by:
combine
in interfaceStatisticAccumulator<Variance>
- Parameters:
other
- Another statistic to be combined.- Returns:
this
instance after combiningother
.
-
setBiased
Sets the value of the biased flag. The default value isfalse
.If
false
the sum of squared deviations from the sample mean is normalised byn - 1
wheren
is the number of samples. This is Bessel's correction for an unbiased estimator of the variance of a hypothetical infinite population.If
true
the sum of squared deviations is normalised by the number of samplesn
.Note: This option only applies when
n > 1
. The variance ofn = 1
is always 0.This flag only controls the final computation of the statistic. The value of this flag will not affect compatibility between instances during a
combine
operation.- Parameters:
v
- Value.- Returns:
this
instance
-