Package com.google.common.math

Class Stats

  • All Implemented Interfaces:
    Serializable
    @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 floating-point 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 of Number, 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 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.

    Since:
    20.0
    Author:
    Pete Gillin, Kevin Bourrillion
    See Also:
    Serialized Form

    • 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 to double 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 to double 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 to double values (this may cause loss of precision for longs of magnitude over 2^53 (slightly over 9e15))

      • of

        public static Stats of​(DoubleStream values)
        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 a DoubleStream, you should collect the values using toStats() instead.

        Parameters:
        values - a series of values
        Since:
        33.4.0 (but since 28.2 in the JRE flavor)

      • of

        public static Stats of​(IntStream values)
        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 an IntStream, you should collect the values using toStats() instead.

        Parameters:
        values - a series of values
        Since:
        33.4.0 (but since 28.2 in the JRE flavor)

      • of

        public static Stats of​(LongStream values)
        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 a LongStream, you should collect the values using toStats() instead.

        Parameters:
        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))
        Since:
        33.4.0 (but since 28.2 in the JRE flavor)

      • count

        public long count()
        Returns the number of values.

      • 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, or Double.NaN) then the result is Double.NaN.

        Throws:
        IllegalStateException - if the dataset is empty or contains a single value

      • equals

        public boolean equals​(@CheckForNull
                      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.)

        Overrides:
        equals in class Object

      • 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.

        Overrides:
        hashCode in class Object

      • meanOf

        public static double meanOf​(Iterable<? extends Number> 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 to double 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 non-zero.

        The definition of the mean is the same as mean.

        Parameters:
        values - a series of values, which will be converted to double 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 to double 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 by toByteArray().

        Note: No guarantees are made regarding stability of the representation between versions.