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] < 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
  Version:
    $Id: SemiVariance.java 1385386 2012-09-16 22:11:15Z psteitz $
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `SemiVariance.Direction` The direction of the semivariance - either upside or downside.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private boolean` | `biasCorrected` Determines whether or not bias correction is applied when computing the value of the statisic.
    `static SemiVariance.Direction` | `DOWNSIDE_VARIANCE` The DOWNSIDE Direction is used to specify that the observations below the cutoff point will be used to calculate SemiVariance
    `private static long` | `serialVersionUID` Serializable version identifier
    `static SemiVariance.Direction` | `UPSIDE_VARIANCE` The UPSIDE Direction is used to specify that the observations above the cutoff point will be used to calculate SemiVariance.
    `private SemiVariance.Direction` | `varianceDirection` Determines whether to calculate downside or upside SemiVariance.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SemiVariance()` Constructs a SemiVariance with default (true) `biasCorrected` property and default (Downside) `varianceDirection` property.
    `SemiVariance(boolean biasCorrected)` Constructs a SemiVariance with the specified `biasCorrected` property and default (Downside) `varianceDirection` property.
    `SemiVariance(boolean corrected, SemiVariance.Direction direction)` Constructs a SemiVariance with the specified `isBiasCorrected` property and the specified `Direction` property.
    `SemiVariance(SemiVariance.Direction direction)` Constructs a SemiVariance with the specified `Direction` property and default (true) `biasCorrected` property
    `SemiVariance(SemiVariance original)` Copy constructor, creates a new `SemiVariance` identical to the `original`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `SemiVariance` | `copy()` Returns a copy of the statistic with the same internal state.
    `static void` | `copy(SemiVariance source, SemiVariance dest)` Copies source to dest.
    `double` | `evaluate(double[] values, double cutoff)` Returns the `SemiVariance` of the designated values against the cutoff, using instance properties variancDirection and biasCorrection.
    `double` | `evaluate(double[] values, double cutoff, SemiVariance.Direction direction)` Returns the `SemiVariance` of the designated values against the cutoff in the given direction, using the current value of the biasCorrection instance property.
    `double` | `evaluate(double[] values, double cutoff, SemiVariance.Direction direction, boolean corrected, int start, int length)` Returns the `SemiVariance` of the designated values against the cutoff in the given direction with the provided bias correction.
    `double` | `evaluate(double[] values, int start, int length)` Returns the `SemiVariance` of the designated values against the mean, using instance properties varianceDirection and biasCorrection.
    `double` | `evaluate(double[] values, SemiVariance.Direction direction)` This method calculates `SemiVariance` for the entire array against the mean, using the current value of the biasCorrection instance property.
    `SemiVariance.Direction` | `getVarianceDirection()` Returns the varianceDirection property.
    `boolean` | `isBiasCorrected()` Returns true iff biasCorrected property is set to true.
    `void` | `setBiasCorrected(boolean biasCorrected)` Sets the biasCorrected property.
    `void` | `setVarianceDirection(SemiVariance.Direction varianceDirection)` Sets the variance direction

    - ### Methods inherited from class org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic

      `evaluate, evaluate, getData, getDataRef, setData, setData, test, test, test, test`

    - ### Methods inherited from class java.lang.Object

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

- - ### 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

    - #### serialVersionUID

          private static final long serialVersionUID

      Serializable version identifier
      See Also:
        Constant Field Values

    - #### biasCorrected

          private boolean biasCorrected

      Determines whether or not bias correction is applied when computing the value of the statisic. True means that bias is corrected.

    - #### varianceDirection

          private SemiVariance.Direction varianceDirection

      Determines whether to calculate downside or upside 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

    - #### 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 `UnivariateStatistic`
      Specified by:
        `evaluate` in interface `MathArrays.Function`
      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

Copyright (c) 2003-2013 Apache Software Foundation