Stats (Guava: Google Core Libraries for Java 20.0 API)

java.lang.Object
- com.google.common.math.Stats

All Implemented Interfaces:

Serializable
```
@Beta
 @GwtIncompatible
public final class Stats
extends Object
implements Serializable
```
A bundle of statistical summary values -- sum, count, mean/average, min and max, and several forms of variance -- that were computed from a single set of zero or more floating-point values.
There are two ways to obtain a Stats instance:
- If all the values you want to summarize are already known, use the appropriate Stats.of factory method below. Primitive arrays, iterables and iterators of any kind of Number, and primitive varargs are supported.
- Or, to avoid storing up all the data first, create a StatsAccumulator instance, feed values to it as you get them, then call StatsAccumulator.snapshot().
Static convenience methods called meanOf are also provided for users who wish to calculate only the mean.
Java 8 users: If you are not using any of the variance statistics, you may wish to use built-in JDK libraries instead of this class.
Since:

20.0

Author:

Pete Gillin, Kevin Bourrillion

See Also:

Serialized Form

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`long`	`count()` Returns the number of values.
`boolean`	`equals(Object obj)`
`static Stats`	`fromByteArray(byte[] byteArray)` Creates a Stats instance from the given byte representation which was obtained by `toByteArray()`.
`int`	`hashCode()`
`double`	`max()` Returns the highest value in the dataset.
`double`	`mean()` Returns the arithmetic mean of the values.
`static double`	`meanOf(double... values)` Returns the arithmetic mean of the values.
`static double`	`meanOf(int... values)` Returns the arithmetic mean of the values.
`static double`	`meanOf(Iterable<? extends Number> values)` Returns the arithmetic mean of the values.
`static double`	`meanOf(Iterator<? extends Number> values)` Returns the arithmetic mean of the values.
`static double`	`meanOf(long... values)` Returns the arithmetic mean of the values.
`double`	`min()` Returns the lowest value in the dataset.
`static Stats`	`of(double... values)` Returns statistics over a dataset containing the given values.
`static Stats`	`of(int... values)` Returns statistics over a dataset containing the given values.
`static Stats`	`of(Iterable<? extends Number> values)` Returns statistics over a dataset containing the given values.
`static Stats`	`of(Iterator<? extends Number> values)` Returns statistics over a dataset containing the given values.
`static Stats`	`of(long... values)` Returns statistics over a dataset containing the given values.
`double`	`populationStandardDeviation()` Returns the population standard deviation of the values.
`double`	`populationVariance()` Returns the population variance of the values.
`double`	`sampleStandardDeviation()` Returns the corrected sample standard deviation of the values.
`double`	`sampleVariance()` Returns the unbaised sample variance of the values.
`double`	`sum()` Returns the sum of the values.
`byte[]`	`toByteArray()` Gets a byte array representation of this instance.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Method Detail
  - of
```
public static Stats of(Iterable<? extends Number> values)
```
    Returns statistics over a dataset containing the given values.
    
    Parameters:
    
    values - a series of values, which will be converted to double values (this may cause loss of precision)
  - of
```
public static Stats of(Iterator<? extends Number> values)
```
    Returns statistics over a dataset containing the given values.
    
    Parameters:
    
    values - a series of values, which will be converted to double values (this may cause loss of precision)
  - of
```
public static Stats of(double... values)
```
    Returns statistics over a dataset containing the given values.
    
    Parameters:
    
    values - a series of values
  - of
```
public static Stats of(int... values)
```
    Returns statistics over a dataset containing the given values.
    
    Parameters:
    
    values - a series of values
  - of
```
public static Stats of(long... values)
```
    Returns statistics over a dataset containing the given values.
    
    Parameters:
    
    values - 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))
  - count
```
public long count()
```
    Returns the number of values.
  - mean
```
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.
    If you only want to calculate the mean, use {#meanOf} instead of creating a Stats instance.
    
    Throws:
    
    IllegalStateException - if the dataset is empty
  - sum
```
public 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.
  - populationVariance
```
public 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.
    
    Throws:
    
    IllegalStateException - if the dataset is empty
  - populationStandardDeviation
```
public 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.
    
    Throws:
    
    IllegalStateException - if the dataset is empty
  - sampleVariance
```
public double sampleVariance()
```
    Returns the unbaised 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.
    
    Throws:
    
    IllegalStateException - if the dataset is empty or contains a single value
  - sampleStandardDeviation
```
public 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.
    
    Throws:
    
    IllegalStateException - if the dataset is empty or contains a single value
  - min
```
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.
    
    Throws:
    
    IllegalStateException - if the dataset is empty
  - max
```
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.
    
    Throws:
    
    IllegalStateException - if the dataset is empty
  - equals
```
public boolean equals(@Nullable
                      Object obj)
```
    Note: This tests exact equality of the calculated statistics, including the floating point values. It is definitely true for instances constructed from exactly the same values in the same order. It is also true for an instance round-tripped through java serialization. However, floating point rounding errors mean that it may be false for some instances where the statistics are mathematically equal, including the same values in a different order.
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Note: This hash code is consistent with exact equality of the calculated statistics, including the floating point values. See the note on equals(java.lang.Object) for details.
    
    Overrides:
    
    hashCode in class Object
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - meanOf
```
public static double meanOf(Iterable<? extends Number> values)
```
    Returns the arithmetic mean of the values. The count must be non-zero.
    The definition of the mean is the same as mean.
    
    Parameters:
    
    values - a series of values, which will be converted to double values (this may cause loss of precision)
    
    Throws:
    
    IllegalArgumentException - if the dataset is empty
  - meanOf
```
public static double meanOf(Iterator<? extends Number> values)
```
    Returns the arithmetic mean of the values. The count must be non-zero.
    The definition of the mean is the same as mean.
    
    Parameters:
    
    values - a series of values, which will be converted to double values (this may cause loss of precision)
    
    Throws:
    
    IllegalArgumentException - if the dataset is empty
  - meanOf
```
public static double meanOf(double... values)
```
    Returns the arithmetic mean of the values. The count must be non-zero.
    The definition of the mean is the same as mean.
    
    Parameters:
    
    values - a series of values
    
    Throws:
    
    IllegalArgumentException - if the dataset is empty
  - meanOf
```
public static double meanOf(int... values)
```
    Returns the arithmetic mean of the values. The count must be non-zero.
    The definition of the mean is the same as mean.
    
    Parameters:
    
    values - a series of values
    
    Throws:
    
    IllegalArgumentException - if the dataset is empty
  - meanOf
```
public static double meanOf(long... values)
```
    Returns the arithmetic mean of the values. The count must be non-zero.
    The definition of the mean is the same as mean.
    
    Parameters:
    
    values - 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))
    
    Throws:
    
    IllegalArgumentException - if the dataset is empty
  - toByteArray
```
public byte[] toByteArray()
```
    Gets a byte array representation of this instance.
    Note: No guarantees are made regarding stability of the representation between versions.
  - fromByteArray
```
public static Stats fromByteArray(byte[] byteArray)
```
    Creates a Stats instance from the given byte representation which was obtained by toByteArray().
    Note: No guarantees are made regarding stability of the representation between versions.

Class Stats

Method Summary

Methods inherited from class java.lang.Object

Method Detail

of

of

of

of

of

count

mean

Non-finite values

sum

Non-finite values

populationVariance

Non-finite values

populationStandardDeviation

Non-finite values

sampleVariance

Non-finite values

sampleStandardDeviation

Non-finite values

min

Non-finite values

max

Non-finite values

equals

hashCode

toString

meanOf

meanOf

meanOf

meanOf

meanOf

toByteArray

fromByteArray