Package org.apache.commons.statistics.descriptive

Class SumOfSquaredDeviations

java.lang.Object

org.apache.commons.statistics.descriptive.FirstMoment

org.apache.commons.statistics.descriptive.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 2⁶³ (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 Summary

Fields

Modifier and Type	Field	Description
protected double	sumSquaredDev	Sum of squared deviations of the values that have been added.

Fields inherited from class org.apache.commons.statistics.descriptive.FirstMoment

dev, n, nDev

Constructor Summary

Constructors

Modifier	Constructor	Description
(package private)	SumOfSquaredDeviations()	Create an instance.
(package private)	SumOfSquaredDeviations(double sumSquaredDev, double m1, long n)	Create an instance with the given sum of squared deviations and first moment.
private	SumOfSquaredDeviations(double sumSquaredDev, FirstMoment m1)	Create an instance with the given sum of squared deviations and first moment.
(package private)	SumOfSquaredDeviations(SumOfSquaredDeviations 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.
(package private) SumOfSquaredDeviations	combine(SumOfSquaredDeviations other)	Combines the state of another SumOfSquaredDeviations into this one.
(package private) static SumOfSquaredDeviations	create(org.apache.commons.numbers.core.Sum sum, double[] values)	Creates the sum of squared deviations.
private static SumOfSquaredDeviations	create(FirstMoment m1, double[] values)	Creates the sum of squared deviations.
(package private) double	getSumOfSquaredDeviations()	Gets the sum of squared deviations of all input values.
(package private) static SumOfSquaredDeviations	of(double... values)	Returns an instance populated using the input values.

Methods inherited from class org.apache.commons.statistics.descriptive.FirstMoment

combine, getFirstMoment, getFirstMomentDifference, getFirstMomentHalfDifference

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

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.

create

static SumOfSquaredDeviations create(org.apache.commons.numbers.core.Sum sum,
                                     double[] values)

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.

Parameters:

sum - Sum of the values.

values - Values.

Returns:

SumOfSquaredDeviations instance.

create

private static SumOfSquaredDeviations create(FirstMoment m1,
                                             double[] values)

Creates the sum of squared deviations.

Parameters:

m1 - First moment.

values - Values.

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.