Package org.apache.commons.statistics.descriptive

Class SumOfSquaredDeviations

  • All Implemented Interfaces:
    java.util.function.DoubleConsumer
    Direct Known Subclasses:
    SumOfCubedDeviations
    class SumOfSquaredDeviations
extends FirstMoment
    Computes the sum of squared deviations from the sample mean. This statistic is related to the second moment.

    The following recursive updating formula is used:

    Let

    • dev = (current obs - previous mean)
    • n = number of observations (including current obs)

    Then

    new value = old value + dev^2 * (n - 1) / n

    returns the sum of squared deviations of all values seen so far.

    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 and Levesque (1983) Algorithms for Computing the Sample Variance: Analysis and Recommendations. American Statistician, 37, 242-247. doi: 10.2307/2683386
    Since:
    1.1

    • Field Detail

      • sumSquaredDev

        protected double sumSquaredDev
        Sum of squared deviations of the values that have been added.

    • Constructor Detail

      • SumOfSquaredDeviations

        SumOfSquaredDeviations()
        Create an instance.

      • SumOfSquaredDeviations

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

      • SumOfSquaredDeviations

        private SumOfSquaredDeviations​(double sumSquaredDev,
                               FirstMoment m1)
        Create an instance with the given sum of squared deviations and first moment.
        Parameters:
        sumSquaredDev - Sum of squared deviations.
        m1 - First moment.

      • SumOfSquaredDeviations

        SumOfSquaredDeviations​(double sumSquaredDev,
                       double m1,
                       long n)
        Create an instance with the given sum of squared deviations and first moment.

        This constructor is used when creating the moment from integer values.

        Parameters:
        sumSquaredDev - Sum of squared deviations.
        m1 - First moment.
        n - Count of values.

    • Method Detail

      • of

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

        Note: SumOfSquaredDeviations computed using accept may be different from this instance.

        Parameters:
        values - Values.
        Returns:
        SumOfSquaredDeviations instance.

      • ofRange

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

        Note: SumOfSquaredDeviations computed using accept 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:
        SumOfSquaredDeviations instance.

      • createFromRange

        static SumOfSquaredDeviations createFromRange​(org.apache.commons.numbers.core.Sum sum,
                                              double[] values,
                                              int from,
                                              int to)
        Creates the sum of squared deviations.

        Uses the provided sum to create the first moment. 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:
        SumOfSquaredDeviations instance.

      • create

        private static SumOfSquaredDeviations create​(FirstMoment m1,
                                             double[] values,
                                             int from,
                                             int to)
        Creates the sum of squared deviations.
        Parameters:
        m1 - First moment.
        values - Values.
        from - Inclusive start of the range.
        to - Exclusive end of the range.
        Returns:
        SumOfSquaredDeviations instance.

      • 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
        Overrides:
        accept in class FirstMoment
        Parameters:
        value - Value.

      • getSumOfSquaredDeviations

        double getSumOfSquaredDeviations()
        Gets the sum of squared deviations of all input values.
        Returns:
        sum of squared deviations of all values.

      • combine

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