org.apache.commons.math.stat.descriptive.moment

Class SemiVariance

java.lang.Object

org.apache.commons.math.stat.descriptive.AbstractUnivariateStatistic

org.apache.commons.math.stat.descriptive.moment.SemiVariance

All Implemented Interfaces:

java.io.Serializable, UnivariateStatistic

public class SemiVariance
extends AbstractUnivariateStatistic
implements java.io.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

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

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) This method calculates SemiVariance for the entire array against the mean, using instance properties varianceDirection and biasCorrection.
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.math.stat.descriptive.AbstractUnivariateStatistic

evaluate, getData, setData, setData

Methods inherited from class java.lang.Object

equals, 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)

Copy constructor, creates a new SemiVariance identical to the original

Parameters:

original - the SemiVariance instance to copy

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)

Copies source to dest.

Neither source nor dest can be null.

Parameters:

source - SemiVariance to copy

dest - SemiVariance to copy to

Throws:

java.lang.NullPointerException - if either source or dest is null

evaluate

public double evaluate(double[] values)

This method calculates SemiVariance for the entire array against the mean, using instance properties varianceDirection and biasCorrection.

Specified by:

evaluate in interface UnivariateStatistic

Overrides:

evaluate in class AbstractUnivariateStatistic

Parameters:

values - the input array

Returns:

the SemiVariance

Throws:

java.lang.IllegalArgumentException - if values is null

evaluate

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

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

java.lang.IllegalArgumentException - if the parameters are not valid

evaluate

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

Parameters:

values - the input array

direction - the SemiVariance.Direction of the semivariance

Returns:

the SemiVariance

Throws:

java.lang.IllegalArgumentException - if values is null

evaluate

public double evaluate(double[] values,
                       double cutoff)

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 IllegalArgumentException if the array is null.

Parameters:

values - the input array

cutoff - the reference point

Returns:

the SemiVariance

Throws:

java.lang.IllegalArgumentException - if values is null

evaluate

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

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

Returns:

the SemiVariance

Throws:

java.lang.IllegalArgumentException - if values is null

evaluate

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

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:

java.lang.IllegalArgumentException - 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