Class Mean
- All Implemented Interfaces:
DoubleConsumer
,DoubleSupplier
,IntSupplier
,LongSupplier
,DoubleStatistic
,StatisticAccumulator<Mean>
,StatisticResult
\[ \frac{1}{n} \sum_{i=1}^n x_i \]
where \( n \) is the number of samples.
- The result is
NaN
if no values are added. - The result is
NaN
if any of the values isNaN
, or the values include infinite values of opposite sign. - The result is
+/-infinity
if values include infinite values of same sign. - The result is finite if all input values are finite.
The accept(double)
method uses the following recursive updating algorithm
that protects the mean from overflow:
- Initialize \( m_1 \) using the first value
- For each additional value, update using
\( m_{i+1} = m_i + (x - m_i) / (i + 1) \)
The of(double...)
method uses an extended precision sum if the sum is finite.
Otherwise uses a corrected two-pass algorithm, starting with
the recursive updating algorithm mentioned above, and then correcting this by adding the
mean deviation of the data values from the one-pass mean (see Ling (1974)).
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.
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:
- Ling, R.F. (1974) Comparison of Several Algorithms for Computing Sample Means and Variances. Journal of the American Statistical Association, 69, 859-866. doi: 10.2307/2286154
- Since:
- 1.1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final FirstMoment
First moment used to compute the mean. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Mean()
Create an instance.(package private)
Mean
(FirstMoment m1) Creates an instance with a moment. -
Method Summary
Modifier and TypeMethodDescriptionvoid
accept
(double value) Updates the state of the statistic to reflect the addition ofvalue
.Combines the state of theother
statistic into this one.static Mean
create()
Creates an instance.double
Gets the mean of all input values.static Mean
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
Methods inherited from interface org.apache.commons.statistics.descriptive.StatisticResult
getAsBigInteger, getAsInt, getAsLong
-
Field Details
-
firstMoment
First moment used to compute the mean.
-
-
Constructor Details
-
Mean
private Mean()Create an instance. -
Mean
Mean(FirstMoment m1) Creates an instance with a moment.- Parameters:
m1
- First moment.
-
-
Method Details
-
create
Creates an instance.The initial result is
NaN
.- Returns:
Mean
instance.
-
of
Returns an instance populated using the inputvalues
.Note:
Mean
computed usingaccept
may be different from this mean.See
Mean
for details on the computing algorithm.- Parameters:
values
- Values.- Returns:
Mean
instance.
-
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.
-
getAsDouble
public double getAsDouble()Gets the mean of all input values.When no values have been added, the result is
NaN
.- Specified by:
getAsDouble
in interfaceDoubleSupplier
- Returns:
- mean of all values.
-
combine
Description copied from interface:StatisticAccumulator
Combines the state of theother
statistic into this one.- Specified by:
combine
in interfaceStatisticAccumulator<Mean>
- Parameters:
other
- Another statistic to be combined.- Returns:
this
instance after combiningother
.
-