Class IntVariance
- All Implemented Interfaces:
DoubleSupplier
,IntConsumer
,IntSupplier
,LongSupplier
,IntStatistic
,StatisticAccumulator<IntVariance>
,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 zero if there is one 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 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
FieldsModifier and TypeFieldDescriptionprivate boolean
Flag to control if the statistic is biased, or should use a bias correction.private long
Count of values that have been added.(package private) static final int
Small array sample size.private final Int128
Sum of the values.private final UInt128
Sum of the squared values. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Create an instance.private
IntVariance
(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
(IntVariance other) Combines the state of theother
statistic into this one.(package private) double
Compute the mean.private static double
computeSSDevN
(UInt128 sumSq, Int128 sum, long n) Compute the sum-of-squared deviations multiplied by the count of values:n * sum(x^2) - sum(x)^2
.(package private) double
Compute the sum of the squared deviations from the mean.(package private) static double
computeVarianceOrStd
(UInt128 sumSq, Int128 sum, long n, boolean biased, boolean std) Compute the variance (or standard deviation).static IntVariance
create()
Creates an instance.double
Gets the variance of all input values.static IntVariance
of
(int... values) Returns an instance populated using the inputvalues
.setBiased
(boolean v) Sets the value of the biased flag.private static BigInteger
square
(BigInteger x) Convenience method to square a BigInteger.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
-
SMALL_SAMPLE
static final int SMALL_SAMPLESmall array sample size. Used to avoid computing with UInt96 then converting to UInt128.- See Also:
-
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
-
IntVariance
private IntVariance()Create an instance. -
IntVariance
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:
IntVariance
instance.
-
of
Returns an instance populated using the inputvalues
.- Parameters:
values
- Values.- Returns:
IntVariance
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 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.
-
computeVarianceOrStd
Compute the variance (or standard deviation).The
std
flag controls if the result is returned as the standard deviation using thesquare root
function.- Parameters:
sumSq
- Sum of the squared values.sum
- Sum of the values.n
- Count of values that have been added.biased
- Flag to control if the statistic is biased, or should use a bias correction.std
- Flag to control if the statistic is the standard deviation.- Returns:
- the variance (or standard deviation)
-
computeSSDevN
Compute the sum-of-squared deviations multiplied by the count of values:n * sum(x^2) - sum(x)^2
.- Parameters:
sumSq
- Sum of the squared values.sum
- Sum of the values.n
- Count of values that have been added.- Returns:
- the sum-of-squared deviations precursor
-
computeSumOfSquaredDeviations
double computeSumOfSquaredDeviations()Compute the sum of the squared deviations from the mean.This is a helper method used in higher order moments.
- Returns:
- the sum of the squared deviations
-
computeMean
double computeMean()Compute the mean.This is a helper method used in higher order moments.
- Returns:
- the mean
-
square
Convenience method to square a BigInteger.- Parameters:
x
- Value- Returns:
- x^2
-
combine
Description copied from interface:StatisticAccumulator
Combines the state of theother
statistic into this one.- Specified by:
combine
in interfaceStatisticAccumulator<IntVariance>
- 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
-