- com.google.common.math.Stats

All Implemented Interfaces:
```
@Beta
@GwtIncompatible
public final class Stats
extends 
implements 
```
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	Description
`long`	`count()`	Returns the number of values.
`boolean`	`obj)`	Indicates whether some other object is "equal to" this one.
`static Stats`	`fromByteArray(byte[] byteArray)`	Creates a Stats instance from the given byte representation which was obtained by `toByteArray()`.
`int`	`hashCode()`	Returns a hash code value for the object.
`double`	`max()`	Returns the highest value in the dataset.
`double`	`mean()`	Returns the of the values.
`static double`	`meanOf(double... values)`	Returns the of the values.
`static double`	`meanOf(int... values)`	Returns the of the values.
`static double`	`meanOf(long... values)`	Returns the of the values.
`static double`	`<? extends > values)`	Returns the of the values.
`static double`	`<? extends > values)`	Returns the 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(long... values)`	Returns statistics over a dataset containing the given values.
`static Stats`	`<? extends > values)`	Returns statistics over a dataset containing the given values.
`static Stats`	`<? extends > values)`	Returns statistics over a dataset containing the given values.
`static Stats`	`values)`	Returns statistics over a dataset containing the given values.
`static Stats`	`values)`	Returns statistics over a dataset containing the given values.
`static Stats`	`values)`	Returns statistics over a dataset containing the given values.
`double`	`populationStandardDeviation()`	Returns the of the values.
`double`	`populationVariance()`	Returns the of the values.
`double`	`sampleStandardDeviation()`	Returns the of the values.
`double`	`sampleVariance()`	Returns the of the values.
`double`	`sum()`	Returns the sum of the values.
`byte[]`	`toByteArray()`	Gets a byte array representation of this instance.
`static <,StatsAccumulator,Stats>`	`toStats()`	Returns a which accumulates statistics from a of any type of boxed into a `Stats`.
	`toString()`	Returns a string representation of the object.

Methods inherited from class java.lang.
, , , , , , ,

- Method Detail
  - of
```
public static <? extends > 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 <? extends > values)
```
    Returns statistics over a dataset containing the given values. The iterator will be completely consumed by this method.
    
    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))
  - of
```
public static  values)
```
    Returns statistics over a dataset containing the given values. The stream will be completely consumed by this method.
    If you have a Stream<Double> rather than a DoubleStream, you should collect the values using toStats() instead.
    
    Parameters:
    
    values - a series of values
    
    Since:
    
    28.2
  - of
```
public static  values)
```
    Returns statistics over a dataset containing the given values. The stream will be completely consumed by this method.
    If you have a Stream<Integer> rather than an IntStream, you should collect the values using toStats() instead.
    
    Parameters:
    
    values - a series of values
    
    Since:
    
    28.2
  - of
```
public static  values)
```
    Returns statistics over a dataset containing the given values. The stream will be completely consumed by this method.
    If you have a Stream<Long> rather than a LongStream, you should collect the values using toStats() instead.
    
    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))
    
    Since:
    
    28.2
  - toStats
```
public static <,StatsAccumulator,Stats> toStats()
```
    Returns a which accumulates statistics from a of any type of boxed into a Stats. Use by calling boxedNumericStream.collect(toStats()). The numbers will be converted to double values (which may cause loss of precision).
    If you have any of the primitive streams DoubleStream, IntStream, or LongStream, you should use the factory method of(java.lang.Iterable<? extends java.lang.Number>) instead.
    
    Since:
    
    28.2
  - count
```
public long count()
```
    Returns the number of values.
  - mean
```
public double mean()
```
    Returns the 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 then the result is . If it contains both and then the result is . If it contains and finite values only or only, the result is . If it contains and finite values only or only, the result is .
    If you only want to calculate the mean, use meanOf(java.lang.Iterable<? extends java.lang.Number>) instead of creating a Stats instance.
    
    Throws:
    
    - if the dataset is empty
  - sum
```
public double sum()
```
    Returns the sum of the values.
    Non-finite values
    
    If the dataset contains then the result is . If it contains both and then the result is . If it contains and finite values only or only, the result is . If it contains and finite values only or only, the result is .
  - populationVariance
```
public double populationVariance()
```
    Returns the 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 (, , or ) then the result is .
    
    Throws:
    
    - if the dataset is empty
  - populationStandardDeviation
```
public double populationStandardDeviation()
```
    Returns the 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 (, , or ) then the result is .
    
    Throws:
    
    - if the dataset is empty
  - sampleVariance
```
public double sampleVariance()
```
    Returns the 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 (, , or ) then the result is .
    
    Throws:
    
    - if the dataset is empty or contains a single value
  - sampleStandardDeviation
```
public double sampleStandardDeviation()
```
    Returns the 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 (, , or ) then the result is .
    
    Throws:
    
    - 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 then the result is . If it contains and not then the result is . If it contains and finite values only then the result is the lowest finite value. If it contains only then the result is .
    
    Throws:
    
    - 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 then the result is . If it contains and not then the result is . If it contains and finite values only then the result is the highest finite value. If it contains only then the result is .
    
    Throws:
    
    - if the dataset is empty
  - equals
```
public boolean   obj)
```
    Indicates whether some other object is "equal to" this one.
    The equals method implements an equivalence relation on non-null object references:
    
    It is reflexive: for any non-null reference value x, x.equals(x) should return true.
    It is symmetric: for any non-null reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true.
    It is transitive: for any non-null reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true.
    It is consistent: for any non-null reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the objects is modified.
    For any non-null reference value x, x.equals(null) should return false.
    
    The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any non-null reference values x and y, this method returns true if and only if x and y refer to the same object (x == y has the value true).
    Note that it is generally necessary to override the hashCode method whenever this method is overridden, so as to maintain the general contract for the hashCode method, which states that equal objects must have equal hash codes.
    Note: This tests exact equality of the calculated statistics, including the floating point values. Two instances are guaranteed to be considered equal if one is copied from the other using second = new StatsAccumulator().addAll(first).snapshot(), if both were obtained by calling snapshot() on the same StatsAccumulator without adding any values in between the two calls, or if one is obtained from the other after round-tripping through java serialization. However, floating point rounding errors mean that it may be false for some instances where the statistics are mathematically equal, including instances constructed from the same values in a different order... or (in the general case) even in the same order. (It is guaranteed to return true for instances constructed from the same values in the same order if strictfp is in effect, or if the system architecture guarantees strictfp-like semantics.)
    Overrides:
    
    in class
    
    Parameters:
    
    obj - the reference object with which to compare.
    
    Returns:
    
    true if this object is the same as the obj argument; false otherwise.
    
    See Also:
    
    ,
  - hashCode
```
public int hashCode()
```
    Returns a hash code value for the object. This method is supported for the benefit of hash tables such as those provided by .
    The general contract of hashCode is:
    
    Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application.
    If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result.
    It is not required that if two objects are unequal according to the method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hash tables.
    
    As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (The hashCode may or may not be implemented as some function of an object's memory address at some point in time.)
    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:
    
    in class
    
    Returns:
    
    a hash code value for this object.
    
    See Also:
    
    ,
  - toString
```
public  toString()
```
    Description copied from class:
    Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.
    The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:
    
    getClass().getName() + '@' + Integer.toHexString(hashCode())
    Overrides:
    
    in class
    
    Returns:
    
    a string representation of the object.
  - meanOf
```
public static double <? extends > values)
```
    Returns the 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:
    
    - if the dataset is empty
  - meanOf
```
public static double <? extends > values)
```
    Returns the 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:
    
    - if the dataset is empty
  - meanOf
```
public static double meanOf(double... values)
```
    Returns the 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:
    
    - if the dataset is empty
  - meanOf
```
public static double meanOf(int... values)
```
    Returns the 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:
    
    - if the dataset is empty
  - meanOf
```
public static double meanOf(long... values)
```
    Returns the 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:
    
    - 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.

Method Detail

of

of

of

of

of

of

of

of

toStats

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