/* * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.apache.commons.math3.stat.descriptive.moment; import java.io.Serializable; import org.apache.commons.math3.exception.MathIllegalArgumentException; import org.apache.commons.math3.exception.NullArgumentException; import org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic; import org.apache.commons.math3.util.MathUtils; /** *
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 {@link #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 */ public class SemiVariance extends AbstractUnivariateStatistic implements Serializable { /** * The UPSIDE Direction is used to specify that the observations above the * cutoff point will be used to calculate SemiVariance. */ public static final Direction UPSIDE_VARIANCE = Direction.UPSIDE; /** * The DOWNSIDE Direction is used to specify that the observations below * the cutoff point will be used to calculate SemiVariance */ public static final Direction DOWNSIDE_VARIANCE = Direction.DOWNSIDE; /** Serializable version identifier */ private static final long serialVersionUID = -2653430366886024994L; /** * Determines whether or not bias correction is applied when computing the * value of the statisic. True means that bias is corrected. */ private boolean biasCorrected = true; /** * Determines whether to calculate downside or upside SemiVariance. */ private Direction varianceDirection = Direction.DOWNSIDE; /** * Constructs a SemiVariance with default (true)biasCorrected
* property and default (Downside) varianceDirection
property.
*/
public SemiVariance() {
}
/**
* Constructs a SemiVariance with the specified biasCorrected
* property and default (Downside) varianceDirection
property.
*
* @param biasCorrected setting for bias correction - true means
* bias will be corrected and is equivalent to using the argumentless
* constructor
*/
public SemiVariance(final boolean biasCorrected) {
this.biasCorrected = biasCorrected;
}
/**
* Constructs a SemiVariance with the specified Direction
property
* and default (true) biasCorrected
property
*
* @param direction setting for the direction of the SemiVariance
* to calculate
*/
public SemiVariance(final Direction direction) {
this.varianceDirection = direction;
}
/**
* Constructs a SemiVariance with the specified isBiasCorrected
* property and the specified Direction
property.
*
* @param corrected setting for bias correction - true means
* bias will be corrected and is equivalent to using the argumentless
* constructor
*
* @param direction setting for the direction of the SemiVariance
* to calculate
*/
public SemiVariance(final boolean corrected, final Direction direction) {
this.biasCorrected = corrected;
this.varianceDirection = direction;
}
/**
* Copy constructor, creates a new {@code SemiVariance} identical
* to the {@code original}
*
* @param original the {@code SemiVariance} instance to copy
* @throws NullArgumentException if original is null
*/
public SemiVariance(final SemiVariance original) throws NullArgumentException {
copy(original, this);
}
/**
* {@inheritDoc}
*/
@Override
public SemiVariance copy() {
SemiVariance result = new SemiVariance();
// No try-catch or advertised exception because args are guaranteed non-null
copy(this, result);
return result;
}
/**
* Copies source to dest.
* Neither source nor dest can be null.
* * @param source SemiVariance to copy * @param dest SemiVariance to copy to * @throws NullArgumentException if either source or dest is null */ public static void copy(final SemiVariance source, SemiVariance dest) throws NullArgumentException { MathUtils.checkNotNull(source); MathUtils.checkNotNull(dest); dest.setData(source.getDataRef()); dest.biasCorrected = source.biasCorrected; dest.varianceDirection = source.varianceDirection; } /** *Returns the {@link 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.
Returns the {@link 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.
Returns the {@link 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.
Returns the {@link 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.