@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 built-in 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(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 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.
|
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 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} 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 non-finite 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 non-finite 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 non-finite 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 non-finite 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 non-null 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 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.)
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 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())
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–2019. All rights reserved.