Class SemiVariance
- All Implemented Interfaces:
Serializable
,UnivariateStatistic
,MathArrays.Function
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.
- See Also:
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic enum
The direction of the semivariance - either upside or downside. -
Field Summary
Modifier and TypeFieldDescriptionstatic final SemiVariance.Direction
The DOWNSIDE Direction is used to specify that the observations below the cutoff point will be used to calculate SemiVariancestatic final SemiVariance.Direction
The UPSIDE Direction is used to specify that the observations above the cutoff point will be used to calculate SemiVariance. -
Constructor Summary
ConstructorDescriptionConstructs a SemiVariance with default (true)biasCorrected
property and default (Downside)varianceDirection
property.SemiVariance
(boolean biasCorrected) Constructs a SemiVariance with the specifiedbiasCorrected
property and default (Downside)varianceDirection
property.SemiVariance
(boolean corrected, SemiVariance.Direction direction) Constructs a SemiVariance with the specifiedisBiasCorrected
property and the specifiedDirection
property.SemiVariance
(SemiVariance original) Copy constructor, creates a newSemiVariance
identical to theoriginal
.SemiVariance
(SemiVariance.Direction direction) Constructs a SemiVariance with the specifiedDirection
property and default (true)biasCorrected
property -
Method Summary
Modifier and TypeMethodDescriptioncopy()
Returns a copy of the statistic with the same internal state.double
evaluate
(double[] values, double cutoff) Returns theSemiVariance
of the designated values against the cutoff, using instance properties variancDirection and biasCorrection.double
evaluate
(double[] values, double cutoff, SemiVariance.Direction direction) Returns theSemiVariance
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 theSemiVariance
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 theSemiVariance
of the designated values against the mean, using instance properties varianceDirection and biasCorrection.double
evaluate
(double[] values, SemiVariance.Direction direction) This method calculatesSemiVariance
for the entire array against the mean, using the current value of the biasCorrection instance property.Returns the varianceDirection property.boolean
Returns true iff biasCorrected property is set to true.withBiasCorrected
(boolean isBiasCorrected) Returns a copy of this instance with the given biasCorrected setting.withVarianceDirection
(SemiVariance.Direction direction) Returns a copy of this instance with the given direction setting.Methods inherited from class org.hipparchus.stat.descriptive.AbstractUnivariateStatistic
evaluate, getData, getDataRef, setData, setData
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.hipparchus.stat.descriptive.UnivariateStatistic
evaluate
-
Field Details
-
UPSIDE_VARIANCE
The UPSIDE Direction is used to specify that the observations above the cutoff point will be used to calculate SemiVariance. -
DOWNSIDE_VARIANCE
The DOWNSIDE Direction is used to specify that the observations below the cutoff point will be used to calculate SemiVariance
-
-
Constructor Details
-
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 specifiedbiasCorrected
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
Constructs a SemiVariance with the specifiedDirection
property and default (true)biasCorrected
property- Parameters:
direction
- setting for the direction of the SemiVariance to calculate
-
SemiVariance
Constructs a SemiVariance with the specifiedisBiasCorrected
property and the specifiedDirection
property.- Parameters:
corrected
- setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructordirection
- setting for the direction of the SemiVariance to calculate
-
SemiVariance
Copy constructor, creates a newSemiVariance
identical to theoriginal
.- Parameters:
original
- theSemiVariance
instance to copy- Throws:
NullArgumentException
- if original is null
-
-
Method Details
-
copy
Returns a copy of the statistic with the same internal state.- Specified by:
copy
in interfaceUnivariateStatistic
- Specified by:
copy
in classAbstractUnivariateStatistic
- Returns:
- a copy of the statistic
-
evaluate
Returns theSemiVariance
of the designated values against the mean, using instance properties varianceDirection and biasCorrection.Returns
NaN
if the array is empty and throwsIllegalArgumentException
if the array is null.- Specified by:
evaluate
in interfaceMathArrays.Function
- Specified by:
evaluate
in interfaceUnivariateStatistic
- Specified by:
evaluate
in 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 calculatesSemiVariance
for the entire array against the mean, using the current value of the biasCorrection instance property.- Parameters:
values
- the input arraydirection
- theSemiVariance.Direction
of the semivariance- Returns:
- the SemiVariance
- Throws:
MathIllegalArgumentException
- if values is null
-
evaluate
Returns theSemiVariance
of the designated values against the cutoff, using instance properties variancDirection and biasCorrection.Returns
NaN
if the array is empty.- 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 theSemiVariance
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.- Parameters:
values
- the input arraycutoff
- the reference pointdirection
- theSemiVariance.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 theSemiVariance
of the designated values against the cutoff in the given direction with the provided bias correction.Returns
NaN
if the array is empty.- Parameters:
values
- the input arraycutoff
- the reference pointdirection
- theSemiVariance.Direction
of 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.
-
withBiasCorrected
Returns a copy of this instance with the given biasCorrected setting.- Parameters:
isBiasCorrected
- new biasCorrected property value- Returns:
- a copy of this instance with the given bias correction setting
-
getVarianceDirection
Returns the varianceDirection property.- Returns:
- the varianceDirection
-
withVarianceDirection
Returns a copy of this instance with the given direction setting.- Parameters:
direction
- the direction of the semivariance- Returns:
- a copy of this instance with the given direction setting
-