Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.commons.math.stat.descriptive.moment
Class Variance

    java.lang.Object
      org.apache.commons.math.stat.descriptive.AbstractUnivariateStatistic
          org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic
              org.apache.commons.math.stat.descriptive.moment.Variance

All Implemented Interfaces:
  Serializable, StorelessUnivariateStatistic, UnivariateStatistic

public class Variance
extends AbstractStorelessUnivariateStatistic
implements Serializable

Computes the variance of the available values. By default, the unbiased "sample variance" definitional formula is used:

variance = sum((x_i - mean)^2) / (n - 1)

where mean is the `Mean` and `n` is the number of sample observations.

The definitional formula does not have good numerical properties, so this implementation uses updating formulas based on West's algorithm as described in Chan, T. F. andJ. G. Lewis 1979, Communications of the ACM, vol. 22 no. 9, pp. 526-531..

The "population variance" ( sum((x_i - mean)^2) / n ) can also be computed using this statistic. The `isBiasCorrected` property determines whether the "population" or "sample" value is returned by the `evaluate` and `getResult` methods. To compute population variances, set this property to `false.` Note that this implementation is not synchronized. If multiple threads access an instance of this class concurrently, and at least one of the threads invokes the `increment()` or `clear()` method, it must be synchronized externally.

Version:
  $Revision: 1.4 $ $Date: 2004/10/11 06:52:39 $
See Also:
  Serialized Form

Field Summary
`protected boolean` | `incMoment` Boolean test to determine if this Variance should also increment the second moment, this evaluates to false when this Variance is constructed with an external SecondMoment as a parameter.
`protected SecondMoment` | `moment` SecondMoment is used in incremental calculation of Variance
`(package private) static long` | `serialVersionUID` Serializable version identifier

Constructor Summary
`Variance()` Constructs a Variance with default (true) `isBiasCorrected` property.
`Variance(boolean isBiasCorrected)` Constructs a Variance with the specified `isBiasCorrected` property
`Variance(boolean isBiasCorrected, SecondMoment m2)` Constructs a Variance with the specified `isBiasCorrected` property and the supplied external second moment.
`Variance(SecondMoment m2)` Constructs a Variance based on an external second moment.

Method Summary
`void` | `clear()` Clears the internal state of the Statistic
`double` | `evaluate(double[] values)` Returns the variance of the entries in the input array, or `Double.NaN` if the array is empty.
`double` | `evaluate(double[] values, double mean)` Returns the variance of the entries in the input array, using the precomputed mean value.
`double` | `evaluate(double[] values, double mean, int begin, int length)` Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value.
`double` | `evaluate(double[] values, int begin, int length)` Returns the variance of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.
`long` | `getN()` Returns the number of values that have been added.
`double` | `getResult()` Returns the current value of the Statistic.
`void` | `increment(double d)` Updates the internal state of the statistic to reflect the addition of the new value.
`boolean` | `isBiasCorrected()`
`void` | `setBiasCorrected(boolean isBiasCorrected)`

Methods inherited from class org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic
`equals, hashCode, incrementAll, incrementAll`

Methods inherited from class org.apache.commons.math.stat.descriptive.AbstractUnivariateStatistic
`test`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### serialVersionUID

    static final long serialVersionUID

  Serializable version identifier

  See Also:
    Constant Field Values

### moment

    protected SecondMoment moment

  SecondMoment is used in incremental calculation of Variance

### incMoment

    protected boolean incMoment

  Boolean test to determine if this Variance should also increment the second moment, this evaluates to false when this Variance is constructed with an external SecondMoment as a parameter.

Constructor Detail

### Variance

    public Variance()

  Constructs a Variance with default (true) `isBiasCorrected` property.

### Variance

    public Variance(SecondMoment m2)

  Constructs a Variance based on an external second moment.

Parameters:
  `m2` - the SecondMoment (Thrid or Fourth moments work here as well.)

### Variance

    public Variance(boolean isBiasCorrected)

  Constructs a Variance with the specified `isBiasCorrected` property

Parameters:
  `isBiasCorrected` - setting for bias correction - true means bias will be corrected and is equivalent to using the argumentless constructor

### Variance

    public Variance(boolean isBiasCorrected,
                    SecondMoment m2)

  Constructs a Variance with the specified `isBiasCorrected` property and the supplied external second moment.

Parameters:
  `isBiasCorrected` - setting for bias correction - true means bias will be corrected
  `m2` - the SecondMoment (Thrid or Fourth moments work here as well.)

Method Detail

### increment

    public void increment(double d)

  Description copied from interface: `StorelessUnivariateStatistic`
  Updates the internal state of the statistic to reflect the addition of the new value.

  Specified by:
    `increment` in interface `StorelessUnivariateStatistic`
  Specified by:
    `increment` in class `AbstractStorelessUnivariateStatistic`
  See Also:
    `StorelessUnivariateStatistic.increment(double)`

### getResult

    public double getResult()

  Description copied from interface: `StorelessUnivariateStatistic`
  Returns the current value of the Statistic.

  Specified by:
    `getResult` in interface `StorelessUnivariateStatistic`
  Specified by:
    `getResult` in class `AbstractStorelessUnivariateStatistic`
  See Also:
    `StorelessUnivariateStatistic.getResult()`

### getN

    public long getN()

  Description copied from interface: `StorelessUnivariateStatistic`
  Returns the number of values that have been added.

  Specified by:
    `getN` in interface `StorelessUnivariateStatistic`
  Returns:
    the number of values.
  See Also:
    `StorelessUnivariateStatistic.getN()`

### clear

    public void clear()

  Description copied from interface: `StorelessUnivariateStatistic`
  Clears the internal state of the Statistic

  Specified by:
    `clear` in interface `StorelessUnivariateStatistic`
  Specified by:
    `clear` in class `AbstractStorelessUnivariateStatistic`
  See Also:
    `StorelessUnivariateStatistic.clear()`

### evaluate

    public double evaluate(double[] values)

  Returns the variance of the entries in the input array, or `Double.NaN` if the array is empty.

  See `Variance` for details on the computing algorithm.

  Returns 0 for a single-value (i.e. length = 1) sample.

  Throws `IllegalArgumentException` if the array is null.

  Does not change the internal state of the statistic.

  Specified by:
    `evaluate` in interface `UnivariateStatistic`
  Overrides:
    `evaluate` in class `AbstractStorelessUnivariateStatistic`
  Parameters:
    `values` - the input array
  Returns:
    the variance of the values or Double.NaN if length = 0
  Throws:
    `IllegalArgumentException` - if the array is null
  See Also:
    `UnivariateStatistic.evaluate(double[])`

### evaluate

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

  Returns the variance of the entries in the specified portion of the input array, or `Double.NaN` if the designated subarray is empty.

  See `Variance` for details on the computing algorithm.

  Returns 0 for a single-value (i.e. length = 1) sample.

  Does not change the internal state of the statistic.

  Throws `IllegalArgumentException` if the array is null.

  Specified by:
    `evaluate` in interface `UnivariateStatistic`
  Overrides:
    `evaluate` in class `AbstractStorelessUnivariateStatistic`
  Parameters:
    `values` - the input array
    `begin` - index of the first array element to include
    `length` - the number of elements to include
  Returns:
    the variance of the values or Double.NaN if length = 0
  Throws:
    `IllegalArgumentException` - if the array is null or the array index parameters are not valid
  See Also:
    `UnivariateStatistic.evaluate(double[], int, int)`

### evaluate

    public double evaluate(double[] values,
                           double mean,
                           int begin,
                           int length)

  Returns the variance of the entries in the specified portion of the input array, using the precomputed mean value. Returns `Double.NaN` if the designated subarray is empty.

  See `Variance` for details on the computing algorithm.

  The formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. This method is supplied only to save computation when the mean has already been computed.

  Returns 0 for a single-value (i.e. length = 1) sample.

  Throws `IllegalArgumentException` if the array is null.

  Does not change the internal state of the statistic.

  Parameters:
    `values` - the input array
    `mean` - the precomputed mean value
    `begin` - index of the first array element to include
    `length` - the number of elements to include
  Returns:
    the variance of the values or Double.NaN if length = 0
  Throws:
    `IllegalArgumentException` - if the array is null or the array index parameters are not valid

### evaluate

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

  Returns the variance of the entries in the input array, using the precomputed mean value. Returns `Double.NaN` if the array is empty.

  See `Variance` for details on the computing algorithm.

  If `isBiasCorrected` is `true` the formula used assumes that the supplied mean value is the arithmetic mean of the sample data, not a known population parameter. If the mean is a known population parameter, or if the "population" version of the variance is desired, set `isBiasCorrected` to `false` before invoking this method.

  Returns 0 for a single-value (i.e. length = 1) sample.

  Throws `IllegalArgumentException` if the array is null.

  Does not change the internal state of the statistic.

  Parameters:
    `values` - the input array
    `mean` - the precomputed mean value
  Returns:
    the variance of the values or Double.NaN if the array is empty
  Throws:
    `IllegalArgumentException` - if the array is null

### isBiasCorrected

    public boolean isBiasCorrected()

  Returns:
    Returns the isBiasCorrected.

### setBiasCorrected

    public void setBiasCorrected(boolean isBiasCorrected)

  Parameters:
    `isBiasCorrected` - The isBiasCorrected to set.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2004 The Apache Software Foundation. All Rights Reserved.