Class SumOfCubedDeviations

java.lang.Object

org.apache.commons.statistics.descriptive.FirstMoment

org.apache.commons.statistics.descriptive.SumOfSquaredDeviations

org.apache.commons.statistics.descriptive.SumOfCubedDeviations

All Implemented Interfaces:

DoubleConsumer

Direct Known Subclasses:

SumOfFourthDeviations

class SumOfCubedDeviations
extends SumOfSquaredDeviations

Computes the sum of cubed deviations from the sample mean. This statistic is related to the third moment.

Uses a recursive updating formula as defined in Manca and Marin (2010), equation 10. Note that the denominator in the third term in that equation has been corrected to \( (N_1 + N_2)^2 \). Two sum of cubed deviations (SC) can be combined using:

\[ SC(X) = {SC}_1 + {SC}_2 + \frac{3(m_1 - m_2)({s_1}^2 - {s_2}^2) N_1 N_2}{N_1 + N_2} + \frac{(m_1 - m_2)^3((N_2 - N_1) N_1 N_2}{(N_1 + N_2)^2} \]

where \( N \) is the group size, \( m \) is the mean, and \( s^2 \) is the biased variance such that \( s^2 * N \) is the sum of squared deviations from the mean. Note the term \( ({s_1}^2 - {s_2}^2) N_1 N_2 == (ss_1 * N_2 - ss_2 * N_1 \) where \( ss \) is the sum of square deviations.

If \( N_1 \) is size 1 this reduces to:

\[ SC_{N+1} = {SC}_N + \frac{3(x - m) -s^2 N}{N + 1} + \frac{(x - m)^3((N - 1) N}{(N + 1)^2} \]

where \( s^2 N \) is the sum of squared deviations. This updating formula is identical to that used in org.apache.commons.math3.stat.descriptive.moment.ThirdMoment.

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:

• Manca and Marin (2020) Decomposition of the Sum of Cubes, the Sum Raised to the Power of Four and Codeviance. Applied Mathematics, 11, 1013-1020. doi: 10.4236/am.2020.1110067

Since:

1.1

Field Summary

Fields

Modifier and Type	Field	Description
(package private) static final int	LENGTH_TWO	2, the length limit where the sum-of-cubed deviations is zero.
protected double	sumCubedDev	Sum of cubed deviations of the values that have been added.

Fields inherited from class SumOfSquaredDeviations

sumSquaredDev

Fields inherited from class FirstMoment

dev, n, nDev

Constructor Summary

Constructors

Constructor	Description
SumOfCubedDeviations()	Create an instance.
SumOfCubedDeviations(double sc, double ss, double m1, long n)	Create an instance with the given sum of cubed and squared deviations, and first moment.
SumOfCubedDeviations(double sc, SumOfSquaredDeviations ss)	Create an instance with the given sum of cubed and squared deviations.
SumOfCubedDeviations(SumOfCubedDeviations 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) SumOfCubedDeviations	combine(SumOfCubedDeviations other)	Combines the state of another SumOfCubedDeviations into this one.
private static SumOfCubedDeviations	create(SumOfSquaredDeviations ss, double[] values, int from, int to)	Creates the sum of cubed deviations.
(package private) static SumOfCubedDeviations	createFromRange(org.apache.commons.numbers.core.Sum sum, double[] values, int from, int to)	Creates the sum of cubed deviations.
(package private) double	getSumOfCubedDeviations()	Gets the sum of cubed deviations of all input values.
(package private) static SumOfCubedDeviations	of(double... values)	Returns an instance populated using the input values.
(package private) static SumOfCubedDeviations	of(int... values)	Returns an instance populated using the input values.
(package private) static SumOfCubedDeviations	of(long... values)	Returns an instance populated using the input values.
(package private) static SumOfCubedDeviations	ofRange(double[] values, int from, int to)	Returns an instance populated using the specified range of values.
(package private) static SumOfCubedDeviations	ofRange(int[] values, int from, int to)	Returns an instance populated using the specified range of values.
(package private) static SumOfCubedDeviations	ofRange(long[] values, int from, int to)	Returns an instance populated using the specified range of values.
private static double	pow3(double x)	Compute x^3.

Methods inherited from class SumOfSquaredDeviations

combine, getSumOfSquaredDeviations

Methods inherited from class FirstMoment

combine, getFirstMoment, getFirstMomentDifference, getFirstMomentHalfDifference

Methods inherited from class Object

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

Methods inherited from interface DoubleConsumer

andThen

Field Details

LENGTH_TWO

static final int LENGTH_TWO

2, the length limit where the sum-of-cubed deviations is zero.

See Also:

• Constant Field Values

sumCubedDev

protected double sumCubedDev

Sum of cubed deviations of the values that have been added.

Constructor Details

SumOfCubedDeviations

SumOfCubedDeviations()

Create an instance.

SumOfCubedDeviations

SumOfCubedDeviations(SumOfCubedDeviations source)

Copy constructor.

Parameters:

source - Source to copy.

SumOfCubedDeviations

SumOfCubedDeviations(double sc,
 SumOfSquaredDeviations ss)

Create an instance with the given sum of cubed and squared deviations.

Parameters:

sc - Sum of cubed deviations.

ss - Sum of squared deviations.

SumOfCubedDeviations

SumOfCubedDeviations(double sc,
 double ss,
 double m1,
 long n)

Create an instance with the given sum of cubed and squared deviations, and first moment.

Parameters:

sc - Sum of cubed deviations.

ss - Sum of squared deviations.

m1 - First moment.

n - Count of values.

Method Details

of

static SumOfCubedDeviations of(double... values)

Returns an instance populated using the input values.

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

Parameters:

values - Values.

Returns:

SumOfCubedDeviations instance.

ofRange

static SumOfCubedDeviations ofRange(double[] values,
 int from,
 int to)

Returns an instance populated using the specified range of values.

Note: SumOfCubedDeviations 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:

SumOfCubedDeviations instance.

createFromRange

static SumOfCubedDeviations createFromRange(org.apache.commons.numbers.core.Sum sum,
 double[] values,
 int from,
 int to)

Creates the sum of cubed 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:

SumOfCubedDeviations instance.

create

private static SumOfCubedDeviations create(SumOfSquaredDeviations ss,
 double[] values,
 int from,
 int to)

Creates the sum of cubed deviations.

Parameters:

ss - Sum of squared deviations.

values - Values.

from - Inclusive start of the range.

to - Exclusive end of the range.

Returns:

SumOfCubedDeviations instance.

of

static SumOfCubedDeviations of(int... values)

Returns an instance populated using the input values.

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

Parameters:

values - Values.

Returns:

SumOfCubedDeviations instance.

ofRange

static SumOfCubedDeviations ofRange(int[] values,
 int from,
 int to)

Returns an instance populated using the specified range of values.

Note: SumOfCubedDeviations 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:

SumOfCubedDeviations instance.

of

static SumOfCubedDeviations of(long... values)

Returns an instance populated using the input values.

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

Parameters:

values - Values.

Returns:

SumOfCubedDeviations instance.

ofRange

static SumOfCubedDeviations ofRange(long[] values,
 int from,
 int to)

Returns an instance populated using the specified range of values.

Note: SumOfCubedDeviations 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:

SumOfCubedDeviations instance.

Throws:

IndexOutOfBoundsException - if the sub-range is out of bounds

pow3

private static double pow3(double x)

Compute x^3. Uses compound multiplication.

Parameters:

x - Value.

Returns:

x^3

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 SumOfSquaredDeviations

Parameters:

value - Value.

getSumOfCubedDeviations

double getSumOfCubedDeviations()

Gets the sum of cubed deviations of all input values.

Note that the sum is subject to cancellation of potentially large positive and negative terms. A non-finite result may be returned due to intermediate overflow when the exact result may be a representable double.

Note: Any non-finite result should be considered a failed computation. The result is returned as computed and not consolidated to a single NaN. This is done for testing purposes to allow the result to be reported. In particular the sign of an infinity may not indicate the direction of the asymmetry (if any), only the direction of the first overflow in the computation. In the event of further overflow of a term to an opposite signed infinity the sum will be NaN.

Returns:

sum of cubed deviations of all values.

combine

SumOfCubedDeviations combine(SumOfCubedDeviations other)

Combines the state of another SumOfCubedDeviations into this one.

Parameters:

other - Another SumOfCubedDeviations to be combined.

Returns:

this instance after combining other.