org.apache.commons.math3.stat.descriptive.moment

## Class StandardDeviation

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

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

    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:
  $Id: StandardDeviation.java 1416643 2012-12-03 19:37:14Z tn $
See Also:
  Serialized Form

### Field Summary

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

### Constructor Summary

Constructors
Constructor and Description
`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

Methods
`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.math3.stat.descriptive.AbstractStorelessUnivariateStatistic

`equals, hashCode, incrementAll, incrementAll`

### Methods inherited from class org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic

`evaluate, getData, getDataRef, setData, setData, test, test, 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)
                      throws NullArgumentException

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

Parameters:
  `original` - the `StandardDeviation` instance to copy
Throws:
  `NullArgumentException` - if original is null

#### 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)
                    throws MathIllegalArgumentException

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 `MathIllegalArgumentException` if the array is null.

Does not change the internal state of the statistic.

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

#### evaluate

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

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 `MathIllegalArgumentException` if the array is null.

Does not change the internal state of the statistic.

Specified by:
  `evaluate` in interface `UnivariateStatistic`
Specified by:
  `evaluate` in interface `MathArrays.Function`
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:
  `MathIllegalArgumentException` - 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)
                    throws MathIllegalArgumentException

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:
  `MathIllegalArgumentException` - if the array is null or the array index parameters are not valid

#### evaluate

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

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 `MathIllegalArgumentException` 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:
  `MathIllegalArgumentException` - 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)
                     throws NullArgumentException

Copies source to dest.

Neither source nor dest can be null.

Parameters:
  `source` - StandardDeviation to copy
  `dest` - StandardDeviation to copy to
Throws:
  `NullArgumentException` - if either source or dest is null