Class SemiVariance
- java.lang.Object
-
- org.apache.commons.math4.legacy.stat.descriptive.AbstractUnivariateStatistic
-
- org.apache.commons.math4.legacy.stat.descriptive.moment.SemiVariance
-
- All Implemented Interfaces:
MathArrays.Function,UnivariateStatistic
public class SemiVariance extends AbstractUnivariateStatistic
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
xagainst the cutoff valuecutoffto be
Σ (x[i] - target)2 / df
where the sum is taken over allisuch thatx[i] < cutoffanddfis the length ofx(non-bias-corrected) or one less than this number (bias corrected). The upside semivariance is defined similarly, with the sum taken over values ofxthat exceed the cutoff value.The cutoff value defaults to the mean, bias correction defaults to
trueand 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 toevaluate(double[], double, Direction, boolean, int, int).If the input array is null,
evaluatemethods throwIllegalArgumentException.If the array has length 1,0is returned, regardless of the value of thecutoff.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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static classSemiVariance.DirectionThe direction of the semivariance - either upside or downside.
-
Field Summary
Fields Modifier and Type Field Description static SemiVariance.DirectionDOWNSIDE_VARIANCEThe DOWNSIDE Direction is used to specify that the observations below.static SemiVariance.DirectionUPSIDE_VARIANCEThe UPSIDE Direction is used to specify that the observations above the cutoff point will be used to calculate SemiVariance.
-
Constructor Summary
Constructors Constructor Description SemiVariance()Constructs a SemiVariance with default (true)biasCorrectedproperty and default (Downside)varianceDirectionproperty.SemiVariance(boolean biasCorrected)Constructs a SemiVariance with the specifiedbiasCorrectedproperty and default (Downside)varianceDirectionproperty.SemiVariance(boolean corrected, SemiVariance.Direction direction)Constructs a SemiVariance with the specifiedisBiasCorrectedproperty and the specifiedDirectionproperty.SemiVariance(SemiVariance original)Copy constructor, creates a newSemiVarianceidentical to theoriginal.SemiVariance(SemiVariance.Direction direction)Constructs a SemiVariance with the specifiedDirectionproperty.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description SemiVariancecopy()Returns a copy of the statistic with the same internal state.static voidcopy(SemiVariance source, SemiVariance dest)Copies source to dest.doubleevaluate(double[] values, double cutoff)Returns theSemiVarianceof the designated values against the cutoff, using instance properties variancDirection and biasCorrection.doubleevaluate(double[] values, double cutoff, SemiVariance.Direction direction)Returns theSemiVarianceof the designated values against the cutoff in the given direction, using the current value of the biasCorrection instance property.doubleevaluate(double[] values, double cutoff, SemiVariance.Direction direction, boolean corrected, int start, int length)Returns theSemiVarianceof the designated values against the cutoff in the given direction with the provided bias correction.doubleevaluate(double[] values, int start, int length)Returns theSemiVarianceof the designated values against the mean, using instance properties varianceDirection and biasCorrection.doubleevaluate(double[] values, SemiVariance.Direction direction)This method calculatesSemiVariancefor the entire array against the mean, using the current value of the biasCorrection instance property.SemiVariance.DirectiongetVarianceDirection()Returns the varianceDirection property.booleanisBiasCorrected()Returns true iff biasCorrected property is set to true.voidsetBiasCorrected(boolean biasCorrected)Sets the biasCorrected property.voidsetVarianceDirection(SemiVariance.Direction varianceDirection)Sets the variance direction.-
Methods inherited from class org.apache.commons.math4.legacy.stat.descriptive.AbstractUnivariateStatistic
evaluate, evaluate, getData, getDataRef, setData, setData
-
-
-
-
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)biasCorrectedproperty and default (Downside)varianceDirectionproperty.
-
SemiVariance
public SemiVariance(boolean biasCorrected)
Constructs a SemiVariance with the specifiedbiasCorrectedproperty and default (Downside)varianceDirectionproperty.- Parameters:
biasCorrected- setting for bias correction - true means bias will be corrected and is equivalent to using the "no arg" constructor
-
SemiVariance
public SemiVariance(SemiVariance.Direction direction)
Constructs a SemiVariance with the specifiedDirectionproperty. and default (true)biasCorrectedproperty- Parameters:
direction- setting for the direction of the SemiVariance to calculate
-
SemiVariance
public SemiVariance(boolean corrected, SemiVariance.Direction direction)
Constructs a SemiVariance with the specifiedisBiasCorrectedproperty and the specifiedDirectionproperty.- Parameters:
corrected- setting for bias correction - true means bias will be corrected and is equivalent to using the "no arg" constructordirection- setting for the direction of the SemiVariance to calculate
-
SemiVariance
public SemiVariance(SemiVariance original) throws NullArgumentException
Copy constructor, creates a newSemiVarianceidentical to theoriginal.- Parameters:
original- theSemiVarianceinstance 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:
copyin interfaceUnivariateStatistic- Specified by:
copyin classAbstractUnivariateStatistic- 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 copydest- 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
SemiVarianceof the designated values against the mean, using instance properties varianceDirection and biasCorrection.Returns
NaNif the array is empty and throwsIllegalArgumentExceptionif the array is null.- Specified by:
evaluatein interfaceMathArrays.Function- Specified by:
evaluatein interfaceUnivariateStatistic- Specified by:
evaluatein classAbstractUnivariateStatistic- Parameters:
values- the input arraystart- index of the first array element to includelength- 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 calculatesSemiVariancefor the entire array against the mean, using the current value of the biasCorrection instance property.- Parameters:
values- the input arraydirection- theSemiVariance.Directionof the semivariance- Returns:
- the SemiVariance
- Throws:
MathIllegalArgumentException- if values is null
-
evaluate
public double evaluate(double[] values, double cutoff) throws MathIllegalArgumentException
Returns the
SemiVarianceof the designated values against the cutoff, using instance properties variancDirection and biasCorrection.Returns
NaNif the array is empty and throwsMathIllegalArgumentExceptionif the array is null.- Parameters:
values- the input arraycutoff- 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
SemiVarianceof the designated values against the cutoff in the given direction, using the current value of the biasCorrection instance property.Returns
NaNif the array is empty and throwsMathIllegalArgumentExceptionif the array is null.- Parameters:
values- the input arraycutoff- the reference pointdirection- theSemiVariance.Directionof 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
SemiVarianceof the designated values against the cutoff in the given direction with the provided bias correction.Returns
NaNif the array is empty and throwsIllegalArgumentExceptionif the array is null.- Parameters:
values- the input arraycutoff- the reference pointdirection- theSemiVariance.Directionof the semivariancecorrected- the BiasCorrection flagstart- index of the first array element to includelength- 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
-
-