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:
java.util.function.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 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
orcombine
method, it must be synchronized externally.However, it is safe to use
accept
andcombine
asaccumulator
andcombiner
functions ofCollector
on a parallel stream, because the parallel implementation ofStream.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 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 org.apache.commons.statistics.descriptive.SumOfSquaredDeviations
sumSquaredDev
-
Fields inherited from class org.apache.commons.statistics.descriptive.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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
accept(double value)
Updates the state of the statistic to reflect the addition ofvalue
.(package private) SumOfCubedDeviations
combine(SumOfCubedDeviations other)
Combines the state of anotherSumOfCubedDeviations
into this one.(package private) static SumOfCubedDeviations
create(org.apache.commons.numbers.core.Sum sum, double[] values)
Creates the sum of cubed deviations.private static SumOfCubedDeviations
create(SumOfSquaredDeviations ss, double[] values)
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 inputvalues
.(package private) static SumOfCubedDeviations
of(int... values)
Returns an instance populated using the inputvalues
.(package private) static SumOfCubedDeviations
of(long... values)
Returns an instance populated using the inputvalues
.private static double
pow3(double x)
Computex^3
.-
Methods inherited from class org.apache.commons.statistics.descriptive.SumOfSquaredDeviations
combine, getSumOfSquaredDeviations
-
Methods inherited from class org.apache.commons.statistics.descriptive.FirstMoment
combine, getFirstMoment, getFirstMomentDifference, getFirstMomentHalfDifference
-
-
-
-
Field Detail
-
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 Detail
-
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 Detail
-
of
static SumOfCubedDeviations of(double... values)
Returns an instance populated using the inputvalues
.Note:
SumOfCubedDeviations
computed usingaccept
may be different from this instance.- Parameters:
values
- Values.- Returns:
SumOfCubedDeviations
instance.
-
create
static SumOfCubedDeviations create(org.apache.commons.numbers.core.Sum sum, double[] values)
Creates the sum of cubed deviations.Uses the provided
sum
to create the first moment. This method is used byDoubleStatistics
using a sum that can be reused for theSum
statistic.- Parameters:
sum
- Sum of the values.values
- Values.- Returns:
SumOfCubedDeviations
instance.
-
create
private static SumOfCubedDeviations create(SumOfSquaredDeviations ss, double[] values)
Creates the sum of cubed deviations.- Parameters:
ss
- Sum of squared deviations.values
- Values.- Returns:
SumOfCubedDeviations
instance.
-
of
static SumOfCubedDeviations of(int... values)
Returns an instance populated using the inputvalues
.Note:
SumOfCubedDeviations
computed usingaccept
may be different from this instance.- Parameters:
values
- Values.- Returns:
SumOfCubedDeviations
instance.
-
of
static SumOfCubedDeviations of(long... values)
Returns an instance populated using the inputvalues
.Note:
SumOfCubedDeviations
computed usingaccept
may be different from this instance.- Parameters:
values
- Values.- Returns:
SumOfCubedDeviations
instance.
-
pow3
private static double pow3(double x)
Computex^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 ofvalue
.- Specified by:
accept
in interfacejava.util.function.DoubleConsumer
- Overrides:
accept
in classSumOfSquaredDeviations
- 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 anotherSumOfCubedDeviations
into this one.- Parameters:
other
- AnotherSumOfCubedDeviations
to be combined.- Returns:
this
instance after combiningother
.
-
-