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.

Nested and Inner Type Summary

Modifier and Type	Class and Description
public static enum	SemiVariance.Direction The direction of the semivariance - either upside or downside.

Field Summary

Modifier and Type	Field and Description
private boolean	biasCorrected Determines whether or not bias correction is applied when computing the value of the statisic.
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
private static final long	serialVersionUID Serializable version identifier
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.
private SemiVariance.Direction	varianceDirection Determines whether to calculate downside or upside SemiVariance.

Constructor Summary

Access	Constructor and Description
public	SemiVariance() Constructs a SemiVariance with default (true) `biasCorrected` property and default (Downside) `varianceDirection` property.
public	SemiVariance(final boolean setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor biasCorrected) Constructs a SemiVariance with the specified `biasCorrected` property and default (Downside) `varianceDirection` property.
public	SemiVariance(final SemiVariance.Direction setting for the direction of the SemiVariance to calculate direction) Constructs a SemiVariance with the specified `Direction` property and default (true) `biasCorrected` property
public	SemiVariance(final boolean setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor corrected, final SemiVariance.Direction setting for the direction of the SemiVariance to calculate direction) Constructs a SemiVariance with the specified `isBiasCorrected` property and the specified `Direction` property.
public	SemiVariance(final SemiVariance the `SemiVariance` instance to copy original) Copy constructor, creates a new `SemiVariance` identical to the `original`

Method Summary

Modifier and Type	Method and Description
public SemiVariance	copy() Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy. Returns a copy of the statistic with the same internal state.
public static void	copy(final SemiVariance SemiVariance to copy source, SemiVariance SemiVariance to copy to dest) Copies source to dest.
public double	Returns: the SemiVariance evaluate(final double[] the input array values, final int index of the first array element to include start, final int the number of elements to include length) Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.evaluate. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.evaluate. Returns the `SemiVariance` of the designated values against the mean, using instance properties varianceDirection and biasCorrection.
public double	Returns: the SemiVariance evaluate(final double[] the input array values, SemiVariance.Direction the `Direction` of the semivariance direction) This method calculates `SemiVariance` for the entire array against the mean, using the current value of the biasCorrection instance property.
public double	Returns: the SemiVariance evaluate(final double[] the input array values, final double the reference point cutoff) Returns the `SemiVariance` of the designated values against the cutoff, using instance properties variancDirection and biasCorrection.
public double	Returns: the SemiVariance evaluate(final double[] the input array values, final double the reference point cutoff, final SemiVariance.Direction the `Direction` of the semivariance direction) Returns the `SemiVariance` of the designated values against the cutoff in the given direction, using the current value of the biasCorrection instance property.
public double	Returns: the SemiVariance evaluate(final double[] the input array values, final double the reference point cutoff, final SemiVariance.Direction the `Direction` of the semivariance direction, final boolean the BiasCorrection flag corrected, final int index of the first array element to include start, final int the number of elements to include length) Returns the `SemiVariance` of the designated values against the cutoff in the given direction with the provided bias correction.
public SemiVariance.Direction	Returns: the varianceDirection getVarianceDirection() Returns the varianceDirection property.
public boolean	Returns: the value of biasCorrected. isBiasCorrected() Returns true iff biasCorrected property is set to true.
public void	setBiasCorrected(boolean new biasCorrected property value biasCorrected) Sets the biasCorrected property.
public void	setVarianceDirection(SemiVariance.Direction the direction of the semivariance varianceDirection) Sets the variance direction

Inherited from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic:: evaluate evaluate getData getDataRef setData setData test test test test

Field Detail

biasCorrected	back to summary
private boolean biasCorrected Determines whether or not bias correction is applied when computing the value of the statisic. True means that bias is corrected.

DOWNSIDE_VARIANCE	back to summary
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	back to summary
private static final long serialVersionUID Serializable version identifier

UPSIDE_VARIANCE	back to summary
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.

varianceDirection	back to summary
private SemiVariance.Direction varianceDirection Determines whether to calculate downside or upside SemiVariance.

Constructor Detail

SemiVariance	back to summary
public SemiVariance() Constructs a SemiVariance with default (true) `biasCorrected` property and default (Downside) `varianceDirection` property.

SemiVariance back to summary

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

public SemiVariance(final boolean biasCorrected)

Constructs a SemiVariance with the specified biasCorrected property and default (Downside) varianceDirection property.

Parameters

biasCorrected:boolean: setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor

SemiVariance back to summary

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

public SemiVariance(final SemiVariance.Direction direction)

Constructs a SemiVariance with the specified Direction property and default (true) biasCorrected property

Parameters

direction:SemiVariance.Direction: setting for the direction of the SemiVariance to calculate

SemiVariance back to summary

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

public SemiVariance(final boolean corrected, final SemiVariance.Direction direction)

Constructs a SemiVariance with the specified isBiasCorrected property and the specified Direction property.

Parameters

corrected:boolean: setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor
direction:SemiVariance.Direction: setting for the direction of the SemiVariance to calculate

SemiVariance back to summary

SemiVariance	back to summary
public SemiVariance(final SemiVariance original) throws NullArgumentException Copy constructor, creates a new `SemiVariance` identical to the `original` Parameters original:SemiVariance the `SemiVariance` instance to copy Exceptions NullArgumentException: if original is null

public SemiVariance(final SemiVariance original) throws NullArgumentException

Copy constructor, creates a new SemiVariance identical to the original

Parameters

original:SemiVariance: the SemiVariance instance to copy

Exceptions

NullArgumentException:: if original is null

Method Detail

copy	back to summary
public SemiVariance copy() Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy. Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy. Returns a copy of the statistic with the same internal state. Returns:SemiVariance Doc from org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy. a copy of the statistic Annotations @Override

copy

back to summary

public SemiVariance copy()

Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy.

Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy.

Doc from org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.copy.

Returns a copy of the statistic with the same internal state.

Returns:SemiVariance

Doc from org.apache.commons.math3.stat.descriptive.UnivariateStatistic.copy.

a copy of the statistic

Annotations

@Override

copy	back to summary
public static void copy(final SemiVariance source, SemiVariance dest) throws NullArgumentException Copies source to dest. Neither source nor dest can be null. Parameters source:SemiVariance SemiVariance to copy dest:SemiVariance SemiVariance to copy to Exceptions NullArgumentException: if either source or dest is null

copy

back to summary

public static void copy(final SemiVariance source, SemiVariance dest) throws NullArgumentException

Copies source to dest.

Neither source nor dest can be null.

Parameters

source:SemiVariance: SemiVariance to copy
dest:SemiVariance: SemiVariance to copy to

Exceptions

NullArgumentException:: if either source or dest is null

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final int start, final int length) throws MathIllegalArgumentException Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.evaluate. Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.evaluate. 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. Parameters values:double[] the input array start:int index of the first array element to include length:int the number of elements to include Returns:double the SemiVariance Annotations @Override Exceptions MathIllegalArgumentException: if the parameters are not valid

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

Implements abstract org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic.evaluate.

Implements org.apache.commons.math3.stat.descriptive.UnivariateStatistic.evaluate.

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.

Parameters

values:double[]: the input array
start:int: index of the first array element to include
length:int: the number of elements to include

Returns:double

the SemiVariance

Annotations

@Override

Exceptions

MathIllegalArgumentException:: if the parameters are not valid

evaluate back to summary

evaluate	back to summary
public double evaluate(final 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:double[] the input array direction:SemiVariance.Direction the `Direction` of the semivariance Returns:double the SemiVariance Exceptions MathIllegalArgumentException: if values is null

public double evaluate(final 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:double[]: the input array
direction:SemiVariance.Direction: the Direction of the semivariance

Returns:double

the SemiVariance

Exceptions

MathIllegalArgumentException:: if values is null

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final 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:double[] the input array cutoff:double the reference point Returns:double the SemiVariance Exceptions MathIllegalArgumentException: if values is null

public double evaluate(final double[] values, final 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:double[]: the input array
cutoff:double: the reference point

Returns:double

the SemiVariance

Exceptions

MathIllegalArgumentException:: if values is null

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final double cutoff, final 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:double[] the input array cutoff:double the reference point direction:SemiVariance.Direction the `Direction` of the semivariance Returns:double the SemiVariance Exceptions MathIllegalArgumentException: if values is null

public double evaluate(final double[] values, final double cutoff, final 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:double[]: the input array
cutoff:double: the reference point
direction:SemiVariance.Direction: the Direction of the semivariance

Returns:double

the SemiVariance

Exceptions

MathIllegalArgumentException:: if values is null

evaluate back to summary

evaluate	back to summary
public double evaluate(final double[] values, final double cutoff, final SemiVariance.Direction direction, final boolean corrected, final int start, final 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:double[] the input array cutoff:double the reference point direction:SemiVariance.Direction the `Direction` of the semivariance corrected:boolean the BiasCorrection flag start:int index of the first array element to include length:int the number of elements to include Returns:double the SemiVariance Exceptions MathIllegalArgumentException: if the parameters are not valid

public double evaluate(final double[] values, final double cutoff, final SemiVariance.Direction direction, final boolean corrected, final int start, final 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:double[]: the input array
cutoff:double: the reference point
direction:SemiVariance.Direction: the Direction of the semivariance
corrected:boolean: the BiasCorrection flag
start:int: index of the first array element to include
length:int: the number of elements to include

Returns:double

the SemiVariance

Exceptions

MathIllegalArgumentException:: if the parameters are not valid

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

getVarianceDirection

back to summary

public SemiVariance.Direction getVarianceDirection()

Returns the varianceDirection property.

Returns:SemiVariance.Direction: the varianceDirection

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

isBiasCorrected

back to summary

public boolean isBiasCorrected()

Returns true iff biasCorrected property is set to true.

Returns:boolean: the value of biasCorrected.

setBiasCorrected	back to summary
public void setBiasCorrected(boolean biasCorrected) Sets the biasCorrected property. Parameters biasCorrected:boolean new biasCorrected property value

setBiasCorrected

back to summary

public void setBiasCorrected(boolean biasCorrected)

Sets the biasCorrected property.

Parameters

biasCorrected:boolean: new biasCorrected property value

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

setVarianceDirection

back to summary

public void setVarianceDirection(SemiVariance.Direction varianceDirection)

Sets the variance direction

Parameters

varianceDirection:SemiVariance.Direction: the direction of the semivariance

org.apache.commons.math3.stat.descriptive.moment back to summary

public final Enum SemiVariance.Direction

Class Inheritance

extends Enum<SemiVariance.Direction>

java.lang.Object
java.lang.Enum
org.apache.commons.math3.stat.descriptive.moment.SemiVariance.Direction

The direction of the semivariance - either upside or downside. The direction is represented by boolean, with true corresponding to UPSIDE semivariance.

Field Summary

Modifier and Type	Field and Description
private boolean	direction boolean value UPSIDE <-> true
public static final SemiVariance.Direction	DOWNSIDE The DOWNSIDE Direction is used to specify that the observations below the cutoff point will be used to calculate SemiVariance
public static final SemiVariance.Direction	UPSIDE The UPSIDE Direction is used to specify that the observations above the cutoff point will be used to calculate SemiVariance

Constructor Summary

Access	Constructor and Description
private	Direction(boolean boolean value representing the Direction. True corresponds to UPSIDE. b) Create a Direction with the given value.

Method Summary

Modifier and Type	Method and Description
pack-priv boolean	Returns: true if direction is UPSIDE; false otherwise getDirection() Returns the value of this Direction.
public static SemiVariance.Direction	valueOf(String name)
public static SemiVariance.Direction[]	values()

Inherited from java.lang.Enum:: clone compareTo describeConstable equals finalize getDeclaringClass hashCode name ordinal toString valueOf

Field Detail

direction	back to summary
private boolean direction boolean value UPSIDE <-> true

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

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

Constructor Detail

Direction	back to summary
private Direction(boolean b) Create a Direction with the given value. Parameters b:boolean boolean value representing the Direction. True corresponds to UPSIDE.

Direction

back to summary

private Direction(boolean b)

Create a Direction with the given value.

Parameters

b:boolean: boolean value representing the Direction. True corresponds to UPSIDE.

Method Detail

getDirection	back to summary
pack-priv boolean getDirection() Returns the value of this Direction. True corresponds to UPSIDE. Returns:boolean true if direction is UPSIDE; false otherwise

getDirection

back to summary

pack-priv boolean getDirection()

Returns the value of this Direction. True corresponds to UPSIDE.

Returns:boolean: true if direction is UPSIDE; false otherwise

valueOf	back to summary
public static SemiVariance.Direction valueOf(String name)

values	back to summary
public static SemiVariance.Direction[] values()

public Class SemiVariance

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public final Enum SemiVariance.Direction

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail