SemiVariance (Apache Commons Math 3.6.1 API)

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)² / 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

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.

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
`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
`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.

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

Class SemiVariance

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Field Detail

UPSIDE_VARIANCE

DOWNSIDE_VARIANCE

Constructor Detail

SemiVariance

SemiVariance

SemiVariance

SemiVariance

SemiVariance

Method Detail

copy

copy

evaluate

evaluate

evaluate

evaluate

evaluate

isBiasCorrected

setBiasCorrected

getVarianceDirection

setVarianceDirection