Package org.apache.commons.math3.stat.descriptive.moment

Class SemiVariance

java.lang.Object
org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic
org.apache.commons.math3.stat.descriptive.moment.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] invalid input: '<' 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.

Since:
2.1
See Also:

  • Field Details

    • 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 Details

    • 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 Details

    • copy

      public SemiVariance copy()
      Returns a copy of the statistic with the same internal state.
      Specified by:
      copy in interface UnivariateStatistic
      Specified by:
      copy in class AbstractUnivariateStatistic
      Returns:
      a copy of the statistic

    • copy

      public static void copy(SemiVariance source, SemiVariance dest) throws NullArgumentException
      Copies source to dest.

      Neither source nor dest can be null.

      Parameters:
      source - SemiVariance to copy
      dest - SemiVariance to copy to
      Throws:
      NullArgumentException - if either source or dest is null

    • evaluate

      public double evaluate(double[] values, int start, int length) throws MathIllegalArgumentException

      Returns the SemiVariance of the designated values against the mean, using instance properties varianceDirection and biasCorrection.

      Returns NaN if the array is empty and throws IllegalArgumentException if the array is null.

      Specified by:
      evaluate in interface MathArrays.Function
      Specified by:
      evaluate in interface UnivariateStatistic
      Specified by:
      evaluate in class AbstractUnivariateStatistic
      Parameters:
      values - the input array
      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

    • evaluate

      public double evaluate(double[] values, SemiVariance.Direction direction) throws MathIllegalArgumentException
      This method calculates SemiVariance for the entire array against the mean, using the current value of the biasCorrection instance property.
      Parameters:
      values - the input array
      direction - the SemiVariance.Direction of the semivariance
      Returns:
      the SemiVariance
      Throws:
      MathIllegalArgumentException - if values is null

    • 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 and throws MathIllegalArgumentException if the array is null.

      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) throws MathIllegalArgumentException

      Returns the SemiVariance of the designated values against the cutoff in the given direction, using the current value of the biasCorrection instance property.

      Returns NaN if the array is empty and throws MathIllegalArgumentException if the array is null.

      Parameters:
      values - the input array
      cutoff - the reference point
      direction - the SemiVariance.Direction of the semivariance
      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 and throws IllegalArgumentException if the array is null.

      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.

    • setBiasCorrected

      public void setBiasCorrected(boolean biasCorrected)
      Sets the biasCorrected property.
      Parameters:
      biasCorrected - new biasCorrected property value

    • getVarianceDirection

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

    • setVarianceDirection

      public void setVarianceDirection(SemiVariance.Direction varianceDirection)
      Sets the variance direction
      Parameters:
      varianceDirection - the direction of the semivariance