Class LongStandardDeviation
- All Implemented Interfaces:
DoubleSupplier
,IntSupplier
,LongConsumer
,LongSupplier
,LongStatistic
,StatisticAccumulator<LongStandardDeviation>
,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
LongStandardDeviation
(UInt192 sumSq, Int128 sum, int n) Create an instance. -
Method Summary
Modifier and TypeMethodDescriptionvoid
accept
(long value) Updates the state of the statistic to reflect the addition ofvalue
.combine
(LongStandardDeviation other) Combines the state of theother
statistic into this one.static LongStandardDeviation
create()
Creates an instance.double
Gets the standard deviation of all input values.static LongStandardDeviation
of
(long... 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.LongConsumer
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
-
LongStandardDeviation
private LongStandardDeviation()Create an instance. -
LongStandardDeviation
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:
LongStandardDeviation
instance.
-
of
Returns an instance populated using the inputvalues
.- Parameters:
values
- Values.- Returns:
LongStandardDeviation
instance.
-
accept
public void accept(long value) Updates the state of the statistic to reflect the addition ofvalue
.- Specified by:
accept
in interfaceLongConsumer
- 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<LongStandardDeviation>
- 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 seeLongStandardDeviationVariance.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:
-