Class Stats
- All Implemented Interfaces:
Serializable
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 built-in JDK libraries instead of this class.
- Since:
- 20.0
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final int
The size of byte array representation in bytes.private final long
private final double
private final double
private final double
private static final long
private final double
-
Constructor Summary
ConstructorsConstructorDescriptionStats
(long count, double mean, double sumOfSquaresOfDeltas, double min, double max) Internal constructor. -
Method Summary
Modifier and TypeMethodDescriptionlong
count()
Returns the number of values.boolean
static Stats
fromByteArray
(byte[] byteArray) Creates a Stats instance from the given byte representation which was obtained bytoByteArray()
.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
(long... values) Returns the arithmetic mean of the values.static double
Returns the arithmetic mean of the values.static double
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
Returns statistics over a dataset containing the given values.static Stats
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
Returns statistics over a dataset containing the given values.static Stats
of
(LongStream values) Returns statistics over a dataset containing the given values.double
Returns the population standard deviation of the values.double
Returns the population variance of the values.(package private) static Stats
readFrom
(ByteBuffer buffer) Creates a Stats instance from the byte representation read from the givenByteBuffer
.double
Returns the corrected sample standard deviation of the values.double
Returns the unbiased sample variance of the values.double
sum()
Returns the sum of the values.(package private) double
byte[]
Gets a byte array representation of this instance.static Collector
<Number, StatsAccumulator, Stats> toStats()
toString()
(package private) void
writeTo
(ByteBuffer buffer) Writes to the givenByteBuffer
a byte representation of this instance.
-
Field Details
-
count
private final long count -
mean
private final double mean -
sumOfSquaresOfDeltas
private final double sumOfSquaresOfDeltas -
min
private final double min -
max
private final double max -
BYTES
static final int BYTESThe size of byte array representation in bytes.- See Also:
-
serialVersionUID
private static final long serialVersionUID- See Also:
-
-
Constructor Details
-
Stats
Stats(long count, double mean, double sumOfSquaresOfDeltas, double min, double max) Internal constructor. Users should useof(java.lang.Iterable<? extends java.lang.Number>)
orStatsAccumulator.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.
- If
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). - If
count
is 1,sumOfSquaresOfDeltas
must be exactly 0.0 orDouble.NaN
.
- If
-
-
Method Details
-
of
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
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
Returns statistics over a dataset containing the given values.- Parameters:
values
- a series of values
-
of
Returns statistics over a dataset containing the given values.- Parameters:
values
- a series of values
-
of
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))
-
of
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 aDoubleStream
, you should collect the values usingtoStats()
instead.- Parameters:
values
- a series of values- Since:
- 28.2
-
of
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 anIntStream
, you should collect the values usingtoStats()
instead.- Parameters:
values
- a series of values- Since:
- 28.2
-
of
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 aLongStream
, you should collect the values usingtoStats()
instead.- 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))- Since:
- 28.2
-
toStats
Returns aCollector
which accumulates statistics from aStream
of any type of boxedNumber
into aStats
. Use by callingboxedNumericStream.collect(toStats())
. The numbers will be converted todouble
values (which may cause loss of precision).If you have any of the primitive streams
DoubleStream
,IntStream
, orLongStream
, you should use the factory methodof(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 arithmetic mean 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
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.Non-finite 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 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 (
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 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 (
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.
Non-finite values
If the dataset contains any non-finite 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.
Non-finite values
If the dataset contains any non-finite 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 non-zero.Non-finite 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 non-zero.Non-finite 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
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 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 ifstrictfp
is in effect, or if the system architecture guaranteesstrictfp
-like semantics.) -
hashCode
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. -
toString
-
sumOfSquaresOfDeltas
double sumOfSquaresOfDeltas() -
meanOf
Returns the arithmetic mean 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 todouble
values (this may cause loss of precision)- Throws:
IllegalArgumentException
- if the dataset is empty
-
meanOf
Returns the arithmetic mean 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 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 non-zero.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 non-zero.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 non-zero.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.
-
writeTo
Writes to the givenByteBuffer
a byte representation of this instance.Note: No guarantees are made regarding stability of the representation between versions.
- Parameters:
buffer
- AByteBuffer
with at least BYTESBuffer.remaining()
, ordered asByteOrder.LITTLE_ENDIAN
, to which a BYTES-long byte representation of this instance is written. In the process increases the position ofByteBuffer
by BYTES.
-
fromByteArray
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.
-
readFrom
Creates a Stats instance from the byte representation read from the givenByteBuffer
.Note: No guarantees are made regarding stability of the representation between versions.
- Parameters:
buffer
- AByteBuffer
with at least BYTESBuffer.remaining()
, ordered asByteOrder.LITTLE_ENDIAN
, from which a BYTES-long byte representation of this instance is read. In the process increases the position ofByteBuffer
by BYTES.
-