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

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

All Implemented Interfaces:
  java.io.Serializable, StorelessUnivariateStatistic, UnivariateStatistic

    public class StandardDeviation

extends AbstractStorelessUnivariateStatistic
implements java.io.Serializable

Computes the sample standard deviation. The standard deviation is the positive square root of the variance. This implementation wraps a `Variance` instance. The `isBiasCorrected` property of the wrapped Variance instance is exposed, so that this class can be used to compute both the "sample standard deviation" (the square root of the bias-corrected "sample variance") or the "population standard deviation" (the square root of the non-bias-corrected "population variance"). See `Variance` for more information.

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: 811685 $ $Date: 2009-09-05 13:36:48 -0400 (Sat, 05 Sep 2009) $
See Also:
  Serialized Form

Field Summary
`private static long` `serialVersionUID` Serializable version identifier
`private Variance` `variance` Wrapped Variance instance

Constructor Summary
`StandardDeviation()` Constructs a StandardDeviation.
`StandardDeviation(boolean isBiasCorrected)` Contructs a StandardDeviation with the specified value for the `isBiasCorrected` property.
`StandardDeviation(boolean isBiasCorrected, SecondMoment m2)` Contructs a StandardDeviation with the specified value for the `isBiasCorrected` property and the supplied external moment.
`StandardDeviation(SecondMoment m2)` Constructs a StandardDeviation from an external second moment.
`StandardDeviation(StandardDeviation original)` Copy constructor, creates a new `StandardDeviation` identical to the `original`

Method Summary
`void` `clear()` Clears the internal state of the Statistic
`StandardDeviation` `copy()` Returns a copy of the statistic with the same internal state.
`static void` `copy(StandardDeviation source, StandardDeviation dest)` Copies source to dest.
`double` `evaluate(double[] values)` Returns the Standard Deviation of the entries in the input array, or `Double.NaN` if the array is empty.
`double` `evaluate(double[] values, double mean)` Returns the Standard Deviation of the entries in the input array, using the precomputed mean value.
`double` `evaluate(double[] values, double mean, int begin, int length)` Returns the Standard Deviation 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 Standard Deviation 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, test`

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

Field Detail

### serialVersionUID

    private static final long serialVersionUID

  Serializable version identifier

  See Also:
    Constant Field Values

### variance

    private Variance variance

  Wrapped Variance instance

Constructor Detail

### StandardDeviation

    public StandardDeviation()

  Constructs a StandardDeviation. Sets the underlying `Variance` instance's `isBiasCorrected` property to true.

### StandardDeviation

    public StandardDeviation(SecondMoment m2)

  Constructs a StandardDeviation from an external second moment.

  Parameters:
    `m2` - the external moment

### StandardDeviation

    public StandardDeviation(StandardDeviation original)

  Copy constructor, creates a new `StandardDeviation` identical to the `original`

  Parameters:
    `original` - the `StandardDeviation` instance to copy

### StandardDeviation

    public StandardDeviation(boolean isBiasCorrected)

  Contructs a StandardDeviation with the specified value for the `isBiasCorrected` property. If this property is set to `true`, the `Variance` used in computing results will use the bias-corrected, or "sample" formula. See `Variance` for details.

  Parameters:
    `isBiasCorrected` - whether or not the variance computation will use the bias-corrected formula

### StandardDeviation

    public StandardDeviation(boolean isBiasCorrected,
                             SecondMoment m2)

  Contructs a StandardDeviation with the specified value for the `isBiasCorrected` property and the supplied external moment. If `isBiasCorrected` is set to `true`, the `Variance` used in computing results will use the bias-corrected, or "sample" formula. See `Variance` for details.

  Parameters:
    `isBiasCorrected` - whether or not the variance computation will use the bias-corrected formula
    `m2` - the external moment

Method Detail

### increment

    public void increment(double d)

  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`
  Parameters:
    `d` - the new value.

### getN

    public long getN()

  Returns the number of values that have been added.

  Specified by:
    `getN` in interface `StorelessUnivariateStatistic`
  Returns:
    the number of values.

### getResult

    public double getResult()

  Returns the current value of the Statistic.

  Specified by:
    `getResult` in interface `StorelessUnivariateStatistic`
  Specified by:
    `getResult` in class `AbstractStorelessUnivariateStatistic`
  Returns:
    value of the statistic, `Double.NaN` if it has been cleared or just instantiated.

### clear

    public void clear()

  Clears the internal state of the Statistic

  Specified by:
    `clear` in interface `StorelessUnivariateStatistic`
  Specified by:
    `clear` in class `AbstractStorelessUnivariateStatistic`

### evaluate

    public double evaluate(double[] values)

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

  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 standard deviation of the values or Double.NaN if length = 0
  Throws:
    `java.lang.IllegalArgumentException` - if the array is null
  See Also:
    `UnivariateStatistic.evaluate(double[])`

### evaluate

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

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

  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
    `begin` - index of the first array element to include
    `length` - the number of elements to include
  Returns:
    the standard deviation of the values or Double.NaN if length = 0
  Throws:
    `java.lang.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 Standard Deviation 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.

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

  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.

  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 standard deviation of the values or Double.NaN if length = 0
  Throws:
    `java.lang.IllegalArgumentException` - if the array is null or the array index parameters are not valid

### evaluate

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

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

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

  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.

  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 standard deviation of the values or Double.NaN if length = 0
  Throws:
    `java.lang.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.

### copy

    public StandardDeviation copy()

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

  Specified by:
    `copy` in interface `StorelessUnivariateStatistic`
  Specified by:
    `copy` in interface `UnivariateStatistic`
  Specified by:
    `copy` in class `AbstractStorelessUnivariateStatistic`
  Returns:
    a copy of the statistic

### copy

    public static void copy(StandardDeviation source,
                            StandardDeviation dest)

  Copies source to dest.

  Neither source nor dest can be null.

  Parameters:
    `source` - StandardDeviation to copy
    `dest` - StandardDeviation to copy to
  Throws:
    `java.lang.NullPointerException` - if either source or dest is null

Copyright (c) 2003-2011 Apache Software Foundation