Top Description Fields Constructors Methods
com.google.common.math

public final Class StatsAccumulator

extends Object
Class Inheritance
Annotations
@J2ktIncompatible
@GwtIncompatible
@ElementTypesAreNonnullByDefault
Static Imports
com.google.common.base.Preconditions.checkState, com.google.common.math.DoubleUtils.ensureNonNegative, com.google.common.primitives.Doubles.isFinite, java.lang.Double.NaN, .Double.isNaN
A mutable object which accumulates double values and tracks some basic statistics over all the values added so far. The values may be added singly or in groups. This class is not thread safe.
Authors
Pete Gillin, Kevin Bourrillion
Since
20.0

Field Summary

Modifier and TypeField and Description
private long
count

private double
max

private double
mean

private double
min

private double
sumOfSquaresOfDeltas

Constructor Summary

AccessConstructor and Description
public
StatsAccumulator()

Method Summary

Modifier and TypeMethod and Description
public void
add(double value)

Adds the given value to the dataset.

public void
addAll(Iterable<? extends Number>
a series of values, which will be converted to double values (this may cause loss of precision)
values)

Adds the given values to the dataset.

public void
addAll(Iterator<? extends Number>
a series of values, which will be converted to double values (this may cause loss of precision)
values)

Adds the given values to the dataset.

public void
addAll(double...
a series of values
values)

Adds the given values to the dataset.

public void
addAll(int...
a series of values
values)

Adds the given values to the dataset.

public void
addAll(long...
a series of values, which will be converted to double values (this may cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))
values)

Adds the given values to the dataset.

public void
addAll(DoubleStream
a series of values
values)

Adds the given values to the dataset.

public void
addAll(IntStream
a series of values
values)

Adds the given values to the dataset.

public void
addAll(LongStream
a series of values, which will be converted to double values (this may cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))
values)

Adds the given values to the dataset.

public void
addAll(Stats values)

Adds the given statistics to the dataset, as if the individual values used to compute the statistics had been added directly.

public void
addAll(StatsAccumulator values)

Adds the given statistics to the dataset, as if the individual values used to compute the statistics had been added directly.

pack-priv static double
calculateNewMeanNonFinite(double previousMean, double value)

Calculates the new value for the accumulated mean when a value is added, in the case where at least one of the previous mean and the value is non-finite.

public long
count()

Returns the number of values.

public double
max()

Returns the highest value in the dataset.

public double
mean()

Returns the arithmetic mean of the values.

private void
merge(long otherCount, double otherMean, double otherSumOfSquaresOfDeltas, double otherMin, double otherMax)

public double
min()

Returns the lowest value in the dataset.

public final double
populationStandardDeviation()

Returns the population standard deviation of the values.

public final double
populationVariance()

Returns the population variance of the values.

public final double
sampleStandardDeviation()

Returns the corrected sample standard deviation of the values.

public final double
sampleVariance()

Returns the unbiased sample variance of the values.

public Stats
snapshot()

Returns an immutable snapshot of the current statistics.

public final double
sum()

Returns the sum of the values.

pack-priv double
sumOfSquaresOfDeltas()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

countback to summary
private long count
maxback to summary
private double max
meanback to summary
private double mean
minback to summary
private double min
sumOfSquaresOfDeltasback to summary
private double sumOfSquaresOfDeltas

Constructor Detail

StatsAccumulatorback to summary
public StatsAccumulator()

Method Detail

addback to summary
public void add(double value)

Adds the given value to the dataset.

addAllback to summary
public void addAll(Iterable<? extends Number> values)

Adds the given values to the dataset.

Parameters
values:Iterable<? extends Number>

a series of values, which will be converted to double values (this may cause loss of precision)

addAllback to summary
public void addAll(Iterator<? extends Number> values)

Adds the given values to the dataset.

Parameters
values:Iterator<? extends Number>

a series of values, which will be converted to double values (this may cause loss of precision)

addAllback to summary
public void addAll(double... values)

Adds the given values to the dataset.

Parameters
values:double[]

a series of values

addAllback to summary
public void addAll(int... values)

Adds the given values to the dataset.

Parameters
values:int[]

a series of values

addAllback to summary
public void addAll(long... values)

Adds the given values to the dataset.

Parameters
values:long[]

a series of values, which will be converted to double values (this may cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))

addAllback to summary
public void addAll(DoubleStream values)

Adds the given values to the dataset. The stream will be completely consumed by this method.

Parameters
values:DoubleStream

a series of values

Since
28.2
addAllback to summary
public void addAll(IntStream values)

Adds the given values to the dataset. The stream will be completely consumed by this method.

Parameters
values:IntStream

a series of values

Since
28.2
addAllback to summary
public void addAll(LongStream values)

Adds the given values to the dataset. The stream will be completely consumed by this method.

Parameters
values:LongStream

a series of values, which will be converted to double values (this may cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))

Since
28.2
addAllback to summary
public void addAll(Stats values)

Adds the given statistics to the dataset, as if the individual values used to compute the statistics had been added directly.

addAllback to summary
public void addAll(StatsAccumulator values)

Adds the given statistics to the dataset, as if the individual values used to compute the statistics had been added directly.

Since
28.2
calculateNewMeanNonFiniteback to summary
pack-priv static double calculateNewMeanNonFinite(double previousMean, double value)

Calculates the new value for the accumulated mean when a value is added, in the case where at least one of the previous mean and the value is non-finite.

countback to summary
public long count()

Returns the number of values.

maxback to summary
public double max()

Returns the highest value in the dataset. The count must be non-zero.

Non-finite values

If the dataset contains Double#NaN then the result is Double#NaN. If it contains Double#POSITIVE_INFINITY and not Double#NaN then the result is Double#POSITIVE_INFINITY. If it contains Double#NEGATIVE_INFINITY and finite values only then the result is the highest finite value. If it contains Double#NEGATIVE_INFINITY only then the result is Double#NEGATIVE_INFINITY.

Exceptions
IllegalStateException:
if the dataset is empty
meanback to summary
public double mean()

Returns the arithmetic mean of the values. The count must be non-zero.

If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.

Non-finite values

If the dataset contains Double#NaN then the result is Double#NaN. If it contains both Double#POSITIVE_INFINITY and Double#NEGATIVE_INFINITY then the result is Double#NaN. If it contains Double#POSITIVE_INFINITY and finite values only or Double#POSITIVE_INFINITY only, the result is Double#POSITIVE_INFINITY. If it contains Double#NEGATIVE_INFINITY and finite values only or Double#NEGATIVE_INFINITY only, the result is Double#NEGATIVE_INFINITY.

Exceptions
IllegalStateException:
if the dataset is empty
mergeback to summary
private void merge(long otherCount, double otherMean, double otherSumOfSquaresOfDeltas, double otherMin, double otherMax)
minback to summary
public double min()

Returns the lowest value in the dataset. The count must be non-zero.

Non-finite values

If the dataset contains Double#NaN then the result is Double#NaN. If it contains Double#NEGATIVE_INFINITY and not Double#NaN then the result is Double#NEGATIVE_INFINITY. If it contains Double#POSITIVE_INFINITY and finite values only then the result is the lowest finite value. If it contains Double#POSITIVE_INFINITY only then the result is Double#POSITIVE_INFINITY.

Exceptions
IllegalStateException:
if the dataset is empty
populationStandardDeviationback to summary
public final double populationStandardDeviation()

Returns the population standard deviation of the values. The count must be non-zero.

This is guaranteed to return zero if the dataset contains only exactly one finite value. It is not guaranteed to return zero when the dataset consists of the same value multiple times, due to numerical errors. However, it is guaranteed never to return a negative result.

Non-finite values

If the dataset contains any non-finite values (Double#POSITIVE_INFINITY, Double#NEGATIVE_INFINITY, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty
populationVarianceback to summary
public final double populationVariance()

Returns the population variance of the values. The count must be non-zero.

This is guaranteed to return zero if the dataset contains only exactly one finite value. It is not guaranteed to return zero when the dataset consists of the same value multiple times, due to numerical errors. However, it is guaranteed never to return a negative result.

Non-finite values

If the dataset contains any non-finite values (Double#POSITIVE_INFINITY, Double#NEGATIVE_INFINITY, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty
sampleStandardDeviationback to summary
public final double sampleStandardDeviation()

Returns the corrected sample standard deviation of the values. If this dataset is a sample drawn from a population, this is an estimator of the population standard deviation of the population which is less biased than populationStandardDeviation() (the unbiased estimator depends on the distribution). The count must be greater than one.

This is not guaranteed to return zero when the dataset consists of the same value multiple times, due to numerical errors. However, it is guaranteed never to return a negative result.

Non-finite values

If the dataset contains any non-finite values (Double#POSITIVE_INFINITY, Double#NEGATIVE_INFINITY, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty or contains a single value
sampleVarianceback to summary
public final double sampleVariance()

Returns the unbiased sample variance of the values. If this dataset is a sample drawn from a population, this is an unbiased estimator of the population variance of the population. The count must be greater than one.

This is not guaranteed to return zero when the dataset consists of the same value multiple times, due to numerical errors. However, it is guaranteed never to return a negative result.

Non-finite values

If the dataset contains any non-finite values (Double#POSITIVE_INFINITY, Double#NEGATIVE_INFINITY, or Double#NaN) then the result is Double#NaN.

Exceptions
IllegalStateException:
if the dataset is empty or contains a single value
snapshotback to summary
public Stats snapshot()

Returns an immutable snapshot of the current statistics.

sumback to summary
public final double sum()

Returns the sum of the values.

Non-finite values

If the dataset contains Double#NaN then the result is Double#NaN. If it contains both Double#POSITIVE_INFINITY and Double#NEGATIVE_INFINITY then the result is Double#NaN. If it contains Double#POSITIVE_INFINITY and finite values only or Double#POSITIVE_INFINITY only, the result is Double#POSITIVE_INFINITY. If it contains Double#NEGATIVE_INFINITY and finite values only or Double#NEGATIVE_INFINITY only, the result is Double#NEGATIVE_INFINITY.

sumOfSquaresOfDeltasback to summary
pack-priv double sumOfSquaresOfDeltas()