Package 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:
  `Serializable`, `StorelessUnivariateStatistic`, `UnivariateStatistic`, `MathArrays.Function`

public class StandardDeviation extends AbstractStorelessUnivariateStatistic implements 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.

See Also:
  - Serialized Form

## Constructor Summary

Constructors
Constructor
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

Modifier and Type
Method
Description
`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`

## Constructor Details

### 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 Details

### 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 `MathArrays.Function`
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:
  `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 `MathArrays.Function`
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:
  `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