Class StandardDeviation
- All Implemented Interfaces:
DoubleConsumer
,DoubleSupplier
,IntSupplier
,LongSupplier
,DoubleStatistic
,StatisticAccumulator<StandardDeviation>
,StatisticResult
\[ \sqrt{ \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. Omitting the square root,
this provides 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.
Note however that square root is a concave function and thus introduces negative bias
(by Jensen's inequality), which depends on the distribution, and thus the corrected sample
standard deviation (using Bessel's correction) is less biased, but still biased.
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 standard deviation. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
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
.combine
(StandardDeviation other) Combines the state of theother
statistic into this one.static StandardDeviation
create()
Creates an instance.double
Gets the standard deviation of all input values.static StandardDeviation
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 standard deviation. -
biased
private boolean biasedFlag to control if the statistic is biased, or should use a bias correction.
-
-
Constructor Details
-
StandardDeviation
private StandardDeviation()Create an instance. -
StandardDeviation
StandardDeviation(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:
StandardDeviation
instance.
-
of
Returns an instance populated using the inputvalues
.Note:
StandardDeviation
computed usingaccept
may be different from this standard deviation.See
StandardDeviation
for details on the computing algorithm.- Parameters:
values
- Values.- Returns:
StandardDeviation
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 standard deviation of all input values.When no values have been added, the result is
NaN
.- Specified by:
getAsDouble
in interfaceDoubleSupplier
- Returns:
- standard deviation of all values.
-
combine
Description copied from interface:StatisticAccumulator
Combines the state of theother
statistic into this one.- Specified by:
combine
in interfaceStatisticAccumulator<StandardDeviation>
- Parameters:
other
- Another statistic to be combined.- Returns:
this
instance after combiningother
.
-
setBiased
Sets the value of the biased flag. The default value isfalse
. The bias term refers to the computation of the variance; the standard deviation is returned as the square root of the biased or unbiased sample variance. For further details seeVariance.setBiased
.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- See Also:
-