Class IntStandardDeviation
- All Implemented Interfaces:
DoubleSupplier
,IntConsumer
,IntSupplier
,LongSupplier
,IntStatistic
,StatisticAccumulator<IntStandardDeviation>
,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 zero if there is one 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 implementation uses an exact integer sum to compute the scaled (by \( n \)) sum of squared deviations from the mean; this is normalised by the scaled correction factor.
\[ \frac {n \times \sum_{i=1}^n x_i^2 - (\sum_{i=1}^n x_i)^2}{n \times (n - 1)} \]
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.
This implementation is not thread safe.
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 implementation of Stream.collect()
provides the necessary partitioning, isolation, and merging of results for
safe and efficient parallel execution.
- Since:
- 1.1
- See Also:
-
Field Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Create an instance.private
IntStandardDeviation
(UInt128 sumSq, Int128 sum, int n) Create an instance. -
Method Summary
Modifier and TypeMethodDescriptionvoid
accept
(int value) Updates the state of the statistic to reflect the addition ofvalue
.combine
(IntStandardDeviation other) Combines the state of theother
statistic into this one.static IntStandardDeviation
create()
Creates an instance.double
Gets the standard deviation of all input values.static IntStandardDeviation
of
(int... 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.IntConsumer
andThen
Methods inherited from interface org.apache.commons.statistics.descriptive.StatisticResult
getAsBigInteger, getAsInt, getAsLong
-
Field Details
-
sumSq
Sum of the squared values. -
sum
Sum of the values. -
n
private long nCount of values that have been added. -
biased
private boolean biasedFlag to control if the statistic is biased, or should use a bias correction.
-
-
Constructor Details
-
IntStandardDeviation
private IntStandardDeviation()Create an instance. -
IntStandardDeviation
Create an instance.- Parameters:
sumSq
- Sum of the squared values.sum
- Sum of the values.n
- Count of values that have been added.
-
-
Method Details
-
create
Creates an instance.The initial result is
NaN
.- Returns:
IntStandardDeviation
instance.
-
of
Returns an instance populated using the inputvalues
.- Parameters:
values
- Values.- Returns:
IntStandardDeviation
instance.
-
accept
public void accept(int value) Updates the state of the statistic to reflect the addition ofvalue
.- Specified by:
accept
in interfaceIntConsumer
- 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<IntStandardDeviation>
- 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 seeIntVarianceVariance.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:
-