@Beta @GwtIncompatible public final class Stats extends Object implements Serializable
There are two ways to obtain a Stats
instance:
Stats.of
factory method below. Primitive arrays, iterables and iterators of any kind of
Number
, and primitive varargs are supported.
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 builtin JDK libraries instead of this class.
Modifier and Type  Method and Description 

long 
count()
Returns the number of values.

boolean 
equals(@Nullable 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 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 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(DoubleStream 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(IntStream 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.

static Stats 
of(LongStream 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.

static Collector<Number,StatsAccumulator,Stats> 
toStats()

String 
toString()
Returns a string representation of the object.

public static Stats of(Iterable<? extends Number> values)
values
 a series of values, which will be converted to double
values (this may
cause loss of precision)public static Stats of(Iterator<? extends Number> values)
values
 a series of values, which will be converted to double
values (this may
cause loss of precision)public static Stats of(double... values)
values
 a series of valuespublic static Stats of(int... values)
values
 a series of valuespublic static Stats of(long... values)
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))public static Stats of(DoubleStream values)
If you have a Stream<Double>
rather than a DoubleStream
, you should collect
the values using toStats()
instead.
values
 a series of valuespublic static Stats of(IntStream values)
If you have a Stream<Integer>
rather than an IntStream
, you should collect
the values using toStats()
instead.
values
 a series of valuespublic static Stats of(LongStream values)
If you have a Stream<Long>
rather than a LongStream
, you should collect the
values using toStats()
instead.
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))public static Collector<Number,StatsAccumulator,Stats> toStats()
Collector
which accumulates statistics from a Stream
of any type of boxed Number
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.
public long count()
public double mean()
If these values are a sample drawn from a population, this is also an unbiased estimator of the arithmetic mean of the population.
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(java.lang.Iterable<? extends java.lang.Number>)
instead of creating a Stats
instance.
IllegalStateException
 if the dataset is emptypublic double sum()
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
.
public double populationVariance()
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.
If the dataset contains any nonfinite values (Double.POSITIVE_INFINITY
, Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
IllegalStateException
 if the dataset is emptypublic double populationStandardDeviation()
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.
If the dataset contains any nonfinite values (Double.POSITIVE_INFINITY
, Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
IllegalStateException
 if the dataset is emptypublic double sampleVariance()
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.
If the dataset contains any nonfinite values (Double.POSITIVE_INFINITY
, Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
IllegalStateException
 if the dataset is empty or contains a single valuepublic double sampleStandardDeviation()
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.
If the dataset contains any nonfinite values (Double.POSITIVE_INFINITY
, Double.NEGATIVE_INFINITY
, or Double.NaN
) then the result is Double.NaN
.
IllegalStateException
 if the dataset is empty or contains a single valuepublic double min()
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
.
IllegalStateException
 if the dataset is emptypublic double max()
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
.
IllegalStateException
 if the dataset is emptypublic boolean equals(@Nullable Object obj)
The equals
method implements an equivalence relation
on nonnull object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
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.
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 nonnull 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 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 if strictfp
is in effect, or if the system architecture guarantees
strictfp
like semantics.)
equals
in class Object
obj
 the reference object with which to compare.true
if this object is the same as the obj
argument; false
otherwise.Object.hashCode()
,
HashMap
public int hashCode()
HashMap
.
The general contract of hashCode
is:
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.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
Object.equals(java.lang.Object)
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. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
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.
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public String toString()
java.lang.Object
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 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())
public static double meanOf(Iterable<? extends Number> values)
The definition of the mean is the same as mean
.
values
 a series of values, which will be converted to double
values (this may
cause loss of precision)IllegalArgumentException
 if the dataset is emptypublic static double meanOf(Iterator<? extends Number> values)
The definition of the mean is the same as mean
.
values
 a series of values, which will be converted to double
values (this may
cause loss of precision)IllegalArgumentException
 if the dataset is emptypublic static double meanOf(double... values)
The definition of the mean is the same as mean
.
values
 a series of valuesIllegalArgumentException
 if the dataset is emptypublic static double meanOf(int... values)
The definition of the mean is the same as mean
.
values
 a series of valuesIllegalArgumentException
 if the dataset is emptypublic static double meanOf(long... values)
The definition of the mean is the same as mean
.
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))IllegalArgumentException
 if the dataset is emptypublic byte[] toByteArray()
Note: No guarantees are made regarding stability of the representation between versions.
public static Stats fromByteArray(byte[] byteArray)
toByteArray()
.
Note: No guarantees are made regarding stability of the representation between versions.
Copyright © 2010–2020. All rights reserved.