Package org.apache.commons.statistics.descriptive

Class FirstMoment

  • All Implemented Interfaces:
    java.util.function.DoubleConsumer
    Direct Known Subclasses:
    SumOfSquaredDeviations
    class FirstMoment
extends java.lang.Object
implements java.util.function.DoubleConsumer
    Computes the first moment (arithmetic mean) using the definitional formula: 
    mean = sum(x_i) / n

    To limit numeric errors, the value of the statistic is computed using the following recursive updating algorithm:

    1. Initialize m = the first value
    2. For each additional value, update using
      m = m + (new value - m) / (number of observations)

    Returns NaN if the dataset is empty. Note that NaN may also be returned if the input includes NaN and / or infinite values of opposite sign.

    Supports up to 263 (exclusive) observations. This implementation does not check for overflow of the count.

    Note that this implementation is not synchronized. If multiple threads access an instance of this class concurrently, and at least one of the threads invokes the accept or combine method, it must be synchronized externally.

    However, it is safe to use accept and combine as accumulator and combiner functions of Collector on a parallel stream, because the parallel implementation of Stream.collect() provides the necessary partitioning, isolation, and merging of results for safe and efficient parallel execution.

    References:

    • Chan, Golub, Levesque (1983) Algorithms for Computing the Sample Variance. American Statistician, vol. 37, no. 3, pp. 242-247.
    • Ling (1974) Comparison of Several Algorithms for Computing Sample Means and Variances. Journal of the American Statistical Association, Vol. 69, No. 348, pp. 859-866.
    Since:
    1.1

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected double dev
      Half the deviation of most recently added value from the previous first moment.
      private static double DOWNSCALE
      The downscale constant.
      private double m1
      First moment of values that have been added.
      protected long n
      Count of values that have been added.
      protected double nDev
      Half the deviation of most recently added value from the previous first moment, normalized by current sample size.
      private double nonFiniteValue
      Running sum of values seen so far.
      private static double RESCALE
      The rescale constant.

    • Constructor Summary

      Constructors 
      Constructor Description
      FirstMoment()
      Create an instance.
      FirstMoment​(double m1, long n)
      Create an instance with the given first moment.
      FirstMoment​(FirstMoment source)
      Copy constructor.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void accept​(double value)
      Updates the state of the statistic to reflect the addition of value.
      private static double combine​(double m1, double m2, long n1, long n2)
      Combine the moments.
      (package private) FirstMoment combine​(FirstMoment other)
      Combines the state of another FirstMoment into this one.
      private static double computeNonFiniteValue​(double[] values)
      Compute the result in the event of non-finite values.
      private static FirstMoment create​(double[] values)
      Creates the first moment using a rolling algorithm.
      (package private) static FirstMoment create​(org.apache.commons.numbers.core.Sum sum, double[] values)
      Creates the first moment.
      (package private) double getFirstMoment()
      Gets the first moment of all input values.
      (package private) double getFirstMomentDifference​(FirstMoment other)
      Gets the difference of the first moment between this moment and the other moment.
      (package private) double getFirstMomentHalfDifference​(FirstMoment other)
      Gets the half the difference of the first moment between this moment and the other moment.
      (package private) static FirstMoment of​(double... values)
      Returns an instance populated using the input values.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

      • Methods inherited from interface java.util.function.DoubleConsumer

        andThen

    • Field Detail

      • DOWNSCALE

        private static final double DOWNSCALE
        The downscale constant. Used to avoid overflow for all finite input.
        See Also:
        Constant Field Values

      • n

        protected long n
        Count of values that have been added.

      • dev

        protected double dev
        Half the deviation of most recently added value from the previous first moment. Retained to prevent repeated computation in higher order moments.

        Note: This is (x - m1) / 2. It is computed as a half value to prevent overflow when computing for any finite value x and m.

        This value is not used in the combine(FirstMoment) method.

      • nDev

        protected double nDev
        Half the deviation of most recently added value from the previous first moment, normalized by current sample size. Retained to prevent repeated computation in higher order moments.

        Note: This is (x - m1) / 2n. It is computed as a half value to prevent overflow when computing for any finite value x and m. Note: This value is not used in the combine(FirstMoment) method.

      • m1

        private double m1
        First moment of values that have been added. This is stored as a half value to prevent overflow for any finite input. Benchmarks show this has negligible performance impact.

      • nonFiniteValue

        private double nonFiniteValue
        Running sum of values seen so far. This is not used in the computation of mean. Used as a return value for first moment when it is non-finite.

    • Constructor Detail

      • FirstMoment

        FirstMoment()
        Create an instance.

      • FirstMoment

        FirstMoment​(FirstMoment source)
        Copy constructor.
        Parameters:
        source - Source to copy.

      • FirstMoment

        FirstMoment​(double m1,
            long n)
        Create an instance with the given first moment.

        This constructor is used when creating the moment from a finite sum of values.

        Parameters:
        m1 - First moment.
        n - Count of values.

    • Method Detail

      • of

        static FirstMoment of​(double... values)
        Returns an instance populated using the input values.

        Note: FirstMoment computed using accept(double) may be different from this instance.

        Parameters:
        values - Values.
        Returns:
        FirstMoment instance.

      • create

        static FirstMoment create​(org.apache.commons.numbers.core.Sum sum,
                          double[] values)
        Creates the first moment.

        Uses the provided sum if finite; otherwise reverts to using the rolling moment to protect from overflow and adds a second pass correction term.

        This method is used by DoubleStatistics using a sum that can be reused for the Sum statistic.

        Parameters:
        sum - Sum of the values.
        values - Values.
        Returns:
        FirstMoment instance.

      • create

        private static FirstMoment create​(double[] values)
        Creates the first moment using a rolling algorithm.

        This duplicates the algorithm in the accept(double) method with optimisations due to the processing of an entire array:

        • Avoid updating (unused) class level working variables.
        • Only computing the non-finite value if required.
        Parameters:
        values - Values.
        Returns:
        the first moment

      • computeNonFiniteValue

        private static double computeNonFiniteValue​(double[] values)
        Compute the result in the event of non-finite values.
        Parameters:
        values - Values.
        Returns:
        the non-finite result

      • accept

        public void accept​(double value)
        Updates the state of the statistic to reflect the addition of value.
        Specified by:
        accept in interface java.util.function.DoubleConsumer
        Parameters:
        value - Value.

      • getFirstMoment

        double getFirstMoment()
        Gets the first moment of all input values.

        When no values have been added, the result is NaN.

        Returns:
        First moment of all values, if it is finite; +/-Infinity, if infinities of the same sign have been encountered; NaN otherwise.

      • combine

        FirstMoment combine​(FirstMoment other)
        Combines the state of another FirstMoment into this one.
        Parameters:
        other - Another FirstMoment to be combined.
        Returns:
        this instance after combining other.

      • combine

        private static double combine​(double m1,
                              double m2,
                              long n1,
                              long n2)
        Combine the moments. This method is used to enforce symmetry. It assumes that the two sizes are not identical, and at least one size is non-zero.
        Parameters:
        m1 - Moment 1.
        m2 - Moment 2.
        n1 - Size of sample 1.
        n2 - Size of sample 2.
        Returns:
        the combined first moment

      • getFirstMomentDifference

        double getFirstMomentDifference​(FirstMoment other)
        Gets the difference of the first moment between this moment and the other moment. This is provided for sub-classes.
        Parameters:
        other - Other moment.
        Returns:
        the difference

      • getFirstMomentHalfDifference

        double getFirstMomentHalfDifference​(FirstMoment other)
        Gets the half the difference of the first moment between this moment and the other moment. This is provided for sub-classes.
        Parameters:
        other - Other moment.
        Returns:
        the difference