Class SumOfSquaredDeviations

java.lang.Object
org.apache.commons.statistics.descriptive.FirstMoment
org.apache.commons.statistics.descriptive.SumOfSquaredDeviations
All Implemented Interfaces:
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 Details

    • sumSquaredDev

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

  • Constructor Details

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

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