Class Stats

  • All Implemented Interfaces:
    java.io.Serializable

    @Beta
    @GwtIncompatible
    public final class Stats
    extends java.lang.Object
    implements java.io.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
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field 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 Summary

      Constructors 
      Constructor Description
      Stats​(long count, double mean, double sumOfSquaresOfDeltas, double min, double max)
      Internal constructor.
    • Field Detail

      • 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 BYTES
        The size of byte array representation in bytes.
        See Also:
        Constant Field Values
    • Constructor Detail

      • Stats

        Stats​(long count,
              double mean,
              double sumOfSquaresOfDeltas,
              double min,
              double max)
        Internal constructor. Users should use 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.

        • 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 or Double.NaN.
    • Method Detail

      • of

        public static Stats of​(java.lang.Iterable<? extends java.lang.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​(java.util.Iterator<? extends java.lang.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​(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))
      • 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 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.

        Throws:
        java.lang.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 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.

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

        Throws:
        java.lang.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, or Double.NaN) then the result is Double.NaN.

        Throws:
        java.lang.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, or Double.NaN) then the result is Double.NaN.

        Throws:
        java.lang.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 than 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.

        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:
        java.lang.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 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.

        Throws:
        java.lang.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 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.

        Throws:
        java.lang.IllegalStateException - if the dataset is empty
      • equals

        public 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.)

        Overrides:
        equals in class java.lang.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 java.lang.Object
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • sumOfSquaresOfDeltas

        double sumOfSquaresOfDeltas()
      • meanOf

        public static double meanOf​(java.lang.Iterable<? extends java.lang.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:
        java.lang.IllegalArgumentException - if the dataset is empty
      • meanOf

        public static double meanOf​(java.util.Iterator<? extends java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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:
        java.lang.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

        void writeTo​(java.nio.ByteBuffer buffer)
        Writes to the given ByteBuffer a byte representation of this instance.

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

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

      • readFrom

        static Stats readFrom​(java.nio.ByteBuffer buffer)
        Creates a Stats instance from the byte representation read from the given ByteBuffer.

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

        Parameters:
        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.