Class FirstMoment
- All Implemented Interfaces:
DoubleConsumer
- Direct Known Subclasses:
SumOfSquaredDeviations
mean = sum(x_i) / n
To limit numeric errors, the value of the statistic is computed using the following recursive updating algorithm:
- Initialize
m =
the first value - For each additional value, update using
m = m + (new value - m) / (number of observations)
Returns NaN
if the dataset is empty. Note that
NaN
may also be returned if the input includes NaN
and / or infinite
values of opposite sign.
Supports up to 263 (exclusive) observations. This implementation does not check for overflow of the count.
Note that this implementation 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 implementation of Stream.collect()
provides the necessary partitioning, isolation, and merging of results for
safe and efficient parallel execution.
References:
- Chan, Golub, Levesque (1983) Algorithms for Computing the Sample Variance. American Statistician, vol. 37, no. 3, pp. 242-247.
- Ling (1974) Comparison of Several Algorithms for Computing Sample Means and Variances. Journal of the American Statistical Association, Vol. 69, No. 348, pp. 859-866.
- Since:
- 1.1
-
Field Summary
FieldsModifier and TypeFieldDescriptionprotected double
Half the deviation of most recently added value from the previous first moment.private static final double
The downscale constant.private double
First moment of values that have been added.protected long
Count of values that have been added.protected double
Half the deviation of most recently added value from the previous first moment, normalized by current sample size.private double
Running sum of values seen so far.private static final double
The rescale constant. -
Constructor Summary
ConstructorsConstructorDescriptionCreate an instance.FirstMoment
(double m1, long n) Create an instance with the given first moment.FirstMoment
(FirstMoment source) Copy constructor. -
Method Summary
Modifier and TypeMethodDescriptionvoid
accept
(double value) Updates the state of the statistic to reflect the addition ofvalue
.private static double
combine
(double m1, double m2, long n1, long n2) Combine the moments.(package private) FirstMoment
combine
(FirstMoment other) Combines the state of anotherFirstMoment
into this one.private static double
computeNonFiniteValue
(double[] values) Compute the result in the event of non-finite values.private static FirstMoment
create
(double[] values) Creates the first moment using a rolling algorithm.(package private) static FirstMoment
create
(org.apache.commons.numbers.core.Sum sum, double[] values) Creates the first moment.(package private) double
Gets the first moment of all input values.(package private) double
Gets the difference of the first moment betweenthis
moment and theother
moment.(package private) double
Gets the half the difference of the first moment betweenthis
moment and theother
moment.(package private) static FirstMoment
of
(double... values) Returns an instance populated using the inputvalues
.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
-
Field Details
-
DOWNSCALE
private static final double DOWNSCALEThe downscale constant. Used to avoid overflow for all finite input.- See Also:
-
RESCALE
private static final double RESCALEThe rescale constant.- See Also:
-
n
protected long nCount of values that have been added. -
dev
protected double devHalf the deviation of most recently added value from the previous first moment. Retained to prevent repeated computation in higher order moments.Note: This is (x - m1) / 2. It is computed as a half value to prevent overflow when computing for any finite value x and m.
This value is not used in the
combine(FirstMoment)
method. -
nDev
protected double nDevHalf the deviation of most recently added value from the previous first moment, normalized by current sample size. Retained to prevent repeated computation in higher order moments.Note: This is (x - m1) / 2n. It is computed as a half value to prevent overflow when computing for any finite value x and m. Note: This value is not used in the
combine(FirstMoment)
method. -
m1
private double m1First moment of values that have been added. This is stored as a half value to prevent overflow for any finite input. Benchmarks show this has negligible performance impact. -
nonFiniteValue
private double nonFiniteValueRunning sum of values seen so far. This is not used in the computation of mean. Used as a return value for first moment when it is non-finite.
-
-
Constructor Details
-
FirstMoment
FirstMoment()Create an instance. -
FirstMoment
FirstMoment(FirstMoment source) Copy constructor.- Parameters:
source
- Source to copy.
-
FirstMoment
FirstMoment(double m1, long n) Create an instance with the given first moment.This constructor is used when creating the moment from a finite sum of values.
- Parameters:
m1
- First moment.n
- Count of values.
-
-
Method Details
-
of
Returns an instance populated using the inputvalues
.Note:
FirstMoment
computed usingaccept(double)
may be different from this instance.- Parameters:
values
- Values.- Returns:
FirstMoment
instance.
-
create
Creates the first moment.Uses the provided
sum
if finite; otherwise reverts to using the rolling moment to protect from overflow and adds a second pass correction term.This method is used by
DoubleStatistics
using a sum that can be reused for theSum
statistic.- Parameters:
sum
- Sum of the values.values
- Values.- Returns:
FirstMoment
instance.
-
create
Creates the first moment using a rolling algorithm.This duplicates the algorithm in the
accept(double)
method with optimisations due to the processing of an entire array:- Avoid updating (unused) class level working variables.
- Only computing the non-finite value if required.
- Parameters:
values
- Values.- Returns:
- the first moment
-
computeNonFiniteValue
private static double computeNonFiniteValue(double[] values) Compute the result in the event of non-finite values.- Parameters:
values
- Values.- Returns:
- the non-finite result
-
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.
-
getFirstMoment
double getFirstMoment()Gets the first moment of all input values.When no values have been added, the result is
NaN
.- Returns:
First moment
of all values, if it is finite;+/-Infinity
, if infinities of the same sign have been encountered;NaN
otherwise.
-
combine
Combines the state of anotherFirstMoment
into this one.- Parameters:
other
- AnotherFirstMoment
to be combined.- Returns:
this
instance after combiningother
.
-
combine
private static double combine(double m1, double m2, long n1, long n2) Combine the moments. This method is used to enforce symmetry. It assumes that the two sizes are not identical, and at least one size is non-zero.- Parameters:
m1
- Moment 1.m2
- Moment 2.n1
- Size of sample 1.n2
- Size of sample 2.- Returns:
- the combined first moment
-
getFirstMomentDifference
Gets the difference of the first moment betweenthis
moment and theother
moment. This is provided for sub-classes.- Parameters:
other
- Other moment.- Returns:
- the difference
-
getFirstMomentHalfDifference
Gets the half the difference of the first moment betweenthis
moment and theother
moment. This is provided for sub-classes.- Parameters:
other
- Other moment.- Returns:
- the difference
-