public final class Stats
extends java.lang.Object
implements java.io.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 | Field and Description |
---|---|
(package private) static int |
BYTES
The size of byte array representation in bytes.
|
private long |
count |
private double |
max |
private double |
mean |
private double |
min |
private static long |
serialVersionUID |
private double |
sumOfSquaresOfDeltas |
Constructor and Description |
---|
Stats(long count,
double mean,
double sumOfSquaresOfDeltas,
double min,
double max)
Internal constructor.
|
Modifier and Type | Method and Description |
---|---|
long |
count()
Returns the number of values.
|
boolean |
equals(java.lang.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(java.lang.Iterable<? extends java.lang.Number> values)
Returns the arithmetic mean of the
values.
|
static double |
meanOf(java.util.Iterator<? extends java.lang.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(java.util.stream.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(java.util.stream.IntStream values)
Returns statistics over a dataset containing the given values.
|
static Stats |
of(java.lang.Iterable<? extends java.lang.Number> values)
Returns statistics over a dataset containing the given values.
|
static Stats |
of(java.util.Iterator<? extends java.lang.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(java.util.stream.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.
|
(package private) static Stats |
readFrom(java.nio.ByteBuffer buffer)
Creates a Stats instance from the byte representation read from the given
ByteBuffer . |
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.
|
(package private) double |
sumOfSquaresOfDeltas() |
byte[] |
toByteArray()
Gets a byte array representation of this instance.
|
static java.util.stream.Collector<java.lang.Number,StatsAccumulator,Stats> |
toStats()
Returns a
Collector which accumulates statistics from a Stream
of any type of boxed Number into a Stats . |
java.lang.String |
toString() |
(package private) void |
writeTo(java.nio.ByteBuffer buffer)
Writes to the given
ByteBuffer a byte representation of this instance. |
private final long count
private final double mean
private final double sumOfSquaresOfDeltas
private final double min
private final double max
static final int BYTES
private static final long serialVersionUID
Stats(long count, double mean, double sumOfSquaresOfDeltas, double min, double max)
of(java.lang.Iterable<? extends java.lang.Number>)
or StatsAccumulator.snapshot()
.
To ensure that the created instance obeys its contract, the parameters should satisfy the following constraints. This is the callers responsibility and is not enforced here.
count
is 0, mean
may have any finite value (its only usage will be to
get multiplied by 0 to calculate the sum), and the other parameters may have any values
(they will not be used).
count
is 1, sumOfSquaresOfDeltas
must be exactly 0.0 or Double.NaN
.
public static Stats of(java.lang.Iterable<? extends java.lang.Number> values)
values
- a series of values, which will be converted to double
values (this may
cause loss of precision)public static Stats of(java.util.Iterator<? extends java.lang.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(java.util.stream.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(java.util.stream.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(java.util.stream.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 java.util.stream.Collector<java.lang.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.
java.lang.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
.
java.lang.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
.
java.lang.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
.
java.lang.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
.
java.lang.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
.
java.lang.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
.
java.lang.IllegalStateException
- if the dataset is emptypublic boolean equals(java.lang.Object obj)
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 java.lang.Object
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.
hashCode
in class java.lang.Object
public java.lang.String toString()
toString
in class java.lang.Object
double sumOfSquaresOfDeltas()
public static double meanOf(java.lang.Iterable<? extends java.lang.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)java.lang.IllegalArgumentException
- if the dataset is emptypublic static double meanOf(java.util.Iterator<? extends java.lang.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)java.lang.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 valuesjava.lang.IllegalArgumentException
- if the dataset is emptypublic static double meanOf(int... values)
The definition of the mean is the same as mean
.
values
- a series of valuesjava.lang.IllegalArgumentException
- 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))java.lang.IllegalArgumentException
- if the dataset is emptypublic byte[] toByteArray()
Note: No guarantees are made regarding stability of the representation between versions.
void writeTo(java.nio.ByteBuffer buffer)
ByteBuffer
a byte representation of this instance.
Note: No guarantees are made regarding stability of the representation between versions.
buffer
- A ByteBuffer
with at least BYTES Buffer.remaining()
, ordered as
ByteOrder.LITTLE_ENDIAN
, to which a BYTES-long byte representation of this instance
is written. In the process increases the position of ByteBuffer
by BYTES.public static Stats fromByteArray(byte[] byteArray)
toByteArray()
.
Note: No guarantees are made regarding stability of the representation between versions.
static Stats readFrom(java.nio.ByteBuffer buffer)
ByteBuffer
.
Note: No guarantees are made regarding stability of the representation between versions.
buffer
- A ByteBuffer
with at least BYTES Buffer.remaining()
, ordered as
ByteOrder.LITTLE_ENDIAN
, from which a BYTES-long byte representation of this
instance is read. In the process increases the position of ByteBuffer
by BYTES.