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.

  Version:
    $Id: StandardDeviation.java 1416643 2012-12-03 19:37:14Z tn $
  See Also:
    Serialized Form

- - ### Field Summary

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

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

Copyright (c) 2003-2013 Apache Software Foundation