Class 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 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 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 input values.

        Note: SumOfCubedDeviations computed using accept 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 by DoubleStatistics using a sum that can be reused for the Sum 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 input values.

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

        Parameters:
        values - Values.
        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.
      • 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 java.util.function.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.