Class FirstMoment
- java.lang.Object
-
- org.apache.commons.statistics.descriptive.FirstMoment
-
- All Implemented Interfaces:
java.util.function.DoubleConsumer
- Direct Known Subclasses:
SumOfSquaredDeviations
class FirstMoment extends java.lang.Object implements java.util.function.DoubleConsumer
Computes the first moment (arithmetic mean) using the definitional formula: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 thatNaN
may also be returned if the input includesNaN
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
orcombine
method, it must be synchronized externally.However, it is safe to use
accept
andcombine
asaccumulator
andcombiner
functions ofCollector
on a parallel stream, because the parallel implementation ofStream.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
Fields Modifier and Type Field Description protected double
dev
Half the deviation of most recently added value from the previous first moment.private static double
DOWNSCALE
The downscale constant.private double
m1
First moment of values that have been added.protected long
n
Count of values that have been added.protected double
nDev
Half the deviation of most recently added value from the previous first moment, normalized by current sample size.private double
nonFiniteValue
Running sum of values seen so far.private static double
RESCALE
The rescale constant.
-
Constructor Summary
Constructors Constructor Description FirstMoment()
Create an instance.FirstMoment(double m1, long n)
Create an instance with the given first moment.FirstMoment(FirstMoment source)
Copy constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
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
getFirstMoment()
Gets the first moment of all input values.(package private) double
getFirstMomentDifference(FirstMoment other)
Gets the difference of the first moment betweenthis
moment and theother
moment.(package private) double
getFirstMomentHalfDifference(FirstMoment other)
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
.
-
-
-
Field Detail
-
DOWNSCALE
private static final double DOWNSCALE
The downscale constant. Used to avoid overflow for all finite input.- See Also:
- Constant Field Values
-
RESCALE
private static final double RESCALE
The rescale constant.- See Also:
- Constant Field Values
-
n
protected long n
Count of values that have been added.
-
dev
protected double dev
Half 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 nDev
Half 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 m1
First 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 nonFiniteValue
Running 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 Detail
-
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 Detail
-
of
static FirstMoment of(double... values)
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
static FirstMoment create(org.apache.commons.numbers.core.Sum sum, double[] values)
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
private static FirstMoment create(double[] values)
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 interfacejava.util.function.DoubleConsumer
- 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
FirstMoment combine(FirstMoment other)
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
double getFirstMomentDifference(FirstMoment other)
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
double getFirstMomentHalfDifference(FirstMoment other)
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
-
-