Class Stats
 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 floatingpoint 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 ofNumber
, 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 callStatsAccumulator.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 builtin 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
equals(Object 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 bytoByteArray()
.int
hashCode()
Returns a hash code value for the object.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(long... 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.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
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.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 unbiased 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()
Returns a string representation of the object.



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 todouble
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. The iterator will be completely consumed by this method. Parameters:
values
 a series of values, which will be converted todouble
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 todouble
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 nonzero.If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.
Nonfinite values
If the dataset contains
Double.NaN
then the result isDouble.NaN
. If it contains bothDouble.POSITIVE_INFINITY
andDouble.NEGATIVE_INFINITY
then the result isDouble.NaN
. If it containsDouble.POSITIVE_INFINITY
and finite values only orDouble.POSITIVE_INFINITY
only, the result isDouble.POSITIVE_INFINITY
. If it containsDouble.NEGATIVE_INFINITY
and finite values only orDouble.NEGATIVE_INFINITY
only, the result isDouble.NEGATIVE_INFINITY
.If you only want to calculate the mean, use
meanOf(java.lang.Iterable<? extends java.lang.Number>)
instead of creating aStats
instance. Throws:
IllegalStateException
 if the dataset is empty

sum
public double sum()
Returns the sum of the values.Nonfinite values
If the dataset contains
Double.NaN
then the result isDouble.NaN
. If it contains bothDouble.POSITIVE_INFINITY
andDouble.NEGATIVE_INFINITY
then the result isDouble.NaN
. If it containsDouble.POSITIVE_INFINITY
and finite values only orDouble.POSITIVE_INFINITY
only, the result isDouble.POSITIVE_INFINITY
. If it containsDouble.NEGATIVE_INFINITY
and finite values only orDouble.NEGATIVE_INFINITY
only, the result isDouble.NEGATIVE_INFINITY
.

populationVariance
public double populationVariance()
Returns the population variance of the values. The count must be nonzero.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.
Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
. Throws:
IllegalStateException
 if the dataset is empty

populationStandardDeviation
public double populationStandardDeviation()
Returns the population standard deviation of the values. The count must be nonzero.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.
Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.NaN
. Throws:
IllegalStateException
 if the dataset is empty

sampleVariance
public 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.
Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.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 thanpopulationStandardDeviation()
(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.
Nonfinite values
If the dataset contains any nonfinite values (
Double.POSITIVE_INFINITY
,Double.NEGATIVE_INFINITY
, orDouble.NaN
) then the result isDouble.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 nonzero.Nonfinite values
If the dataset contains
Double.NaN
then the result isDouble.NaN
. If it containsDouble.NEGATIVE_INFINITY
and notDouble.NaN
then the result isDouble.NEGATIVE_INFINITY
. If it containsDouble.POSITIVE_INFINITY
and finite values only then the result is the lowest finite value. If it containsDouble.POSITIVE_INFINITY
only then the result isDouble.POSITIVE_INFINITY
. Throws:
IllegalStateException
 if the dataset is empty

max
public double max()
Returns the highest value in the dataset. The count must be nonzero.Nonfinite values
If the dataset contains
Double.NaN
then the result isDouble.NaN
. If it containsDouble.POSITIVE_INFINITY
and notDouble.NaN
then the result isDouble.POSITIVE_INFINITY
. If it containsDouble.NEGATIVE_INFINITY
and finite values only then the result is the highest finite value. If it containsDouble.NEGATIVE_INFINITY
only then the result isDouble.NEGATIVE_INFINITY
. Throws:
IllegalStateException
 if the dataset is empty

equals
public boolean equals(@CheckForNull Object obj)
Indicates whether some other object is "equal to" this one.The
equals
method implements an equivalence relation on nonnull object references: It is reflexive: for any nonnull reference value
x
,x.equals(x)
should returntrue
.  It is symmetric: for any nonnull reference values
x
andy
,x.equals(y)
should returntrue
if and only ify.equals(x)
returnstrue
.  It is transitive: for any nonnull reference values
x
,y
, andz
, ifx.equals(y)
returnstrue
andy.equals(z)
returnstrue
, thenx.equals(z)
should returntrue
.  It is consistent: for any nonnull reference values
x
andy
, multiple invocations ofx.equals(y)
consistently returntrue
or consistently returnfalse
, provided no information used inequals
comparisons on the objects is modified.  For any nonnull reference value
x
,x.equals(null)
should returnfalse
.
The
equals
method for classObject
implements the most discriminating possible equivalence relation on objects; that is, for any nonnull reference valuesx
andy
, this method returnstrue
if and only ifx
andy
refer to the same object (x == y
has the valuetrue
).Note that it is generally necessary to override the
hashCode
method whenever this method is overridden, so as to maintain the general contract for thehashCode
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 callingsnapshot()
on the sameStatsAccumulator
without adding any values in between the two calls, or if one is obtained from the other after roundtripping 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 ifstrictfp
is in effect, or if the system architecture guaranteesstrictfp
like semantics.) Overrides:
equals
in classObject
 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:
Object.hashCode()
,HashMap
 It is reflexive: for any nonnull reference value

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 byHashMap
.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 inequals
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 thehashCode
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
Object.equals(java.lang.Object)
method, then calling thehashCode
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:
hashCode
in classObject
 Returns:
 a hash code value for this object.
 See Also:
Object.equals(java.lang.Object)
,System.identityHashCode(java.lang.Object)
 Whenever it is invoked on the same object more than once during
an execution of a Java application, the

toString
public String toString()
Description copied from class:java.lang.Object
Returns a string representation of the object. In general, thetoString
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 classObject
returns a string consisting of the name of the class of which the object is an instance, the atsign 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())

meanOf
public static double meanOf(Iterable<? extends Number> values)
Returns the arithmetic mean of the values. The count must be nonzero.The definition of the mean is the same as
mean
. Parameters:
values
 a series of values, which will be converted todouble
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 nonzero.The definition of the mean is the same as
mean
. Parameters:
values
 a series of values, which will be converted todouble
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 nonzero.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 nonzero.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 nonzero.The definition of the mean is the same as
mean
. Parameters:
values
 a series of values, which will be converted todouble
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 bytoByteArray()
.Note: No guarantees are made regarding stability of the representation between versions.

