Package org.hipparchus.stat.descriptive.moment

Class SemiVariance

  • All Implemented Interfaces:
    Serializable, UnivariateStatistic, MathArrays.Function
    public class SemiVariance
extends AbstractUnivariateStatistic
implements Serializable
    Computes the semivariance of a set of values with respect to a given cutoff value.

    We define the downside semivariance of a set of values x against the cutoff value cutoff to be
    Σ (x[i] - target)2 / df
    where the sum is taken over all i such that x[i] < cutoff and df is the length of x (non-bias-corrected) or one less than this number (bias corrected). The upside semivariance is defined similarly, with the sum taken over values of x that exceed the cutoff value.

    The cutoff value defaults to the mean, bias correction defaults to true and the "variance direction" (upside or downside) defaults to downside. The variance direction and bias correction may be set using property setters or their values can provided as parameters to evaluate(double[], double, Direction, boolean, int, int).

    If the input array is null, evaluate methods throw IllegalArgumentException. If the array has length 1, 0 is returned, regardless of the value of the cutoff.

    Note that this class is not intended to be threadsafe. If multiple threads access an instance of this class concurrently, and one or more of these threads invoke property setters, external synchronization must be provided to ensure correct results.

    See Also:
    Serialized Form

    • Field Detail

      • UPSIDE_VARIANCE

        public static final SemiVariance.Direction UPSIDE_VARIANCE
        The UPSIDE Direction is used to specify that the observations above the cutoff point will be used to calculate SemiVariance.

      • DOWNSIDE_VARIANCE

        public static final SemiVariance.Direction DOWNSIDE_VARIANCE
        The DOWNSIDE Direction is used to specify that the observations below the cutoff point will be used to calculate SemiVariance

    • Constructor Detail

      • SemiVariance

        public SemiVariance()
        Constructs a SemiVariance with default (true) biasCorrected property and default (Downside) varianceDirection property.

      • SemiVariance

        public SemiVariance​(boolean biasCorrected)
        Constructs a SemiVariance with the specified biasCorrected property and default (Downside) varianceDirection property.
        Parameters:
        biasCorrected - setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor

      • SemiVariance

        public SemiVariance​(SemiVariance.Direction direction)
        Constructs a SemiVariance with the specified Direction property and default (true) biasCorrected property
        Parameters:
        direction - setting for the direction of the SemiVariance to calculate

      • SemiVariance

        public SemiVariance​(boolean corrected,
                    SemiVariance.Direction direction)
        Constructs a SemiVariance with the specified isBiasCorrected property and the specified Direction property.
        Parameters:
        corrected - setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor
        direction - setting for the direction of the SemiVariance to calculate

      • SemiVariance

        public SemiVariance​(SemiVariance original)
             throws NullArgumentException
        Copy constructor, creates a new SemiVariance identical to the original.
        Parameters:
        original - the SemiVariance instance to copy
        Throws:
        NullArgumentException - if original is null

    • Method Detail

      • evaluate

        public double evaluate​(double[] values,
                       double cutoff)
                throws MathIllegalArgumentException
        Returns the SemiVariance of the designated values against the cutoff, using instance properties variancDirection and biasCorrection.

        Returns NaN if the array is empty.

        Parameters:
        values - the input array
        cutoff - the reference point
        Returns:
        the SemiVariance
        Throws:
        MathIllegalArgumentException - if values is null

      • evaluate

        public double evaluate​(double[] values,
                       double cutoff,
                       SemiVariance.Direction direction,
                       boolean corrected,
                       int start,
                       int length)
                throws MathIllegalArgumentException
        Returns the SemiVariance of the designated values against the cutoff in the given direction with the provided bias correction.

        Returns NaN if the array is empty.

        Parameters:
        values - the input array
        cutoff - the reference point
        direction - the SemiVariance.Direction of the semivariance
        corrected - the BiasCorrection flag
        start - index of the first array element to include
        length - the number of elements to include
        Returns:
        the SemiVariance
        Throws:
        MathIllegalArgumentException - if the parameters are not valid

      • isBiasCorrected

        public boolean isBiasCorrected()
        Returns true iff biasCorrected property is set to true.
        Returns:
        the value of biasCorrected.

      • withBiasCorrected

        public SemiVariance withBiasCorrected​(boolean isBiasCorrected)
        Returns a copy of this instance with the given biasCorrected setting.
        Parameters:
        isBiasCorrected - new biasCorrected property value
        Returns:
        a copy of this instance with the given bias correction setting

      • getVarianceDirection

        public SemiVariance.Direction getVarianceDirection()
        Returns the varianceDirection property.
        Returns:
        the varianceDirection

      • withVarianceDirection

        public SemiVariance withVarianceDirection​(SemiVariance.Direction direction)
        Returns a copy of this instance with the given direction setting.
        Parameters:
        direction - the direction of the semivariance
        Returns:
        a copy of this instance with the given direction setting