Class FirstMoment

java.lang.Object
org.apache.commons.statistics.descriptive.FirstMoment
All Implemented Interfaces:
DoubleConsumer
Direct Known Subclasses:
SumOfSquaredDeviations
class FirstMoment extends Object implements 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 final 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 final 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

    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, int from, int to)
    Compute the result in the event of non-finite values.
    private static FirstMoment
    create(double[] values, int from, int to)
    Creates the first moment using a rolling algorithm.
    (package private) static FirstMoment
    createFromRange(org.apache.commons.numbers.core.Sum sum, double[] values, int from, int to)
    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.
    (package private) static FirstMoment
    ofRange(double[] values, int from, int to)
    Returns an instance populated using the specified range of values.

    Methods inherited from class Object

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

    Methods inherited from interface DoubleConsumer

    andThen

  • Field Details

    • DOWNSCALE

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

    • RESCALE

      private static final double RESCALE
      The rescale constant.
      See Also:

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

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

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

    • ofRange

      static FirstMoment ofRange(double[] values, int from, int to)
      Returns an instance populated using the specified range of values.

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

      Warning: No range checks are performed.

      Parameters:
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      FirstMoment instance.
      Throws:
      IndexOutOfBoundsException - if the sub-range is out of bounds
      Since:
      1.2

    • createFromRange

      static FirstMoment createFromRange(org.apache.commons.numbers.core.Sum sum, double[] values, int from, int to)
      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.

      Warning: No range checks are performed.

      Parameters:
      sum - Sum of the values.
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      FirstMoment instance.

    • create

      private static FirstMoment create(double[] values, int from, int to)
      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.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      Returns:
      the first moment

    • computeNonFiniteValue

      private static double computeNonFiniteValue(double[] values, int from, int to)
      Compute the result in the event of non-finite values.
      Parameters:
      values - Values.
      from - Inclusive start of the range.
      to - Exclusive end of the range.
      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 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