View Javadoc

    1   /*
    2    * Copyright 2003-2004 The Apache Software Foundation.
    3    *
    4    * Licensed under the Apache License, Version 2.0 (the "License");
    5    * you may not use this file except in compliance with the License.
    6    * You may obtain a copy of the License at
    7    *
    8    *      http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   */
    16  package org.apache.commons.math.stat.descriptive.moment;
    17
    18  import java.io.Serializable;
    19
    20  import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
    21
    22  /***
    23   * Computes the sample standard deviation.  The standard deviation
    24   * is the positive square root of the variance.  This implementation wraps a
    25   * {@link Variance} instance.  The <code>isBiasCorrected</code> property of the
    26   * wrapped Variance instance is exposed, so that this class can be used to
    27   * compute both the "sample standard deviation" (the square root of the
    28   * bias-corrected "sample variance") or the "population standard deviation"
    29   * (the square root of the non-bias-corrected "population variance"). See
    30   * {@link Variance} for more information.
    31   * <p>
    32   * <strong>Note that this implementation is not synchronized.</strong> If
    33   * multiple threads access an instance of this class concurrently, and at least
    34   * one of the threads invokes the <code>increment()</code> or
    35   * <code>clear()</code> method, it must be synchronized externally.
    36   *
    37   * @version $Revision: 1.2 $ $Date: 2004/10/11 06:54:05 $
    38   */
    39  public class StandardDeviation extends AbstractStorelessUnivariateStatistic
    40      implements Serializable {
    41
    42      /*** Serializable version identifier */
    43      static final long serialVersionUID = 5728716329662425188L;
    44
    45      /*** Wrapped Variance instance */
    46      private Variance variance = null;
    47
    48      /***
    49       * Constructs a StandardDeviation.  Sets the underlying {@link Variance}
    50       * instance's <code>isBiasCorrected</code> property to true.
    51       */
    52      public StandardDeviation() {
    53          variance = new Variance();
    54      }
    55
    56      /***
    57       * Constructs a StandardDeviation from an external second moment.
    58       *
    59       * @param m2 the external moment
    60       */
    61      public StandardDeviation(final SecondMoment m2) {
    62          variance = new Variance(m2);
    63      }
    64
    65      /***
    66       * Contructs a StandardDeviation with the specified value for the
    67       * <code>isBiasCorrected</code> property.  If this property is set to
    68       * <code>true</code>, the {@link Variance} used in computing results will
    69       * use the bias-corrected, or "sample" formula.  See {@link Variance} for
    70       * details.
    71       *
    72       * @param isBiasCorrected  whether or not the variance computation will use
    73       * the bias-corrected formula
    74       */
    75      public StandardDeviation(boolean isBiasCorrected) {
    76          variance = new Variance(isBiasCorrected);
    77      }
    78
    79      /***
    80       * Contructs a StandardDeviation with the specified value for the
    81       * <code>isBiasCorrected</code> property and the supplied external moment.
    82       * If <code>isBiasCorrected</code> is set to <code>true</code>, the
    83       * {@link Variance} used in computing results will use the bias-corrected,
    84       * or "sample" formula.  See {@link Variance} for details.
    85       *
    86       * @param isBiasCorrected  whether or not the variance computation will use
    87       * the bias-corrected formula
    88        * @param m2 the external moment
    89       */
    90      public StandardDeviation(boolean isBiasCorrected, SecondMoment m2) {
    91          variance = new Variance(isBiasCorrected, m2);
    92      }
    93
    94      /***
    95       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
    96       */
    97      public void increment(final double d) {
    98          variance.increment(d);
    99      }
    100
    101     /***
    102      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getN()
    103      */
    104     public long getN() {
    105         return variance.getN();
    106     }
    107
    108     /***
    109      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult()
    110      */
    111     public double getResult() {
    112         return Math.sqrt(variance.getResult());
    113     }
    114
    115     /***
    116      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear()
    117      */
    118     public void clear() {
    119         variance.clear();
    120     }
    121
    122     /***
    123      * Returns the Standard Deviation of the entries in the input array, or
    124      * <code>Double.NaN</code> if the array is empty.
    125      * <p>
    126      * Returns 0 for a single-value (i.e. length = 1) sample.
    127      * <p>
    128      * Throws <code>IllegalArgumentException</code> if the array is null.
    129      * <p>
    130      * Does not change the internal state of the statistic.
    131      *
    132      * @param values the input array
    133      * @return the standard deviation of the values or Double.NaN if length = 0
    134      * @throws IllegalArgumentException if the array is null
    135      */
    136     public double evaluate(final double[] values)  {
    137         return Math.sqrt(variance.evaluate(values));
    138     }
    139
    140     /***
    141      * Returns the Standard Deviation of the entries in the specified portion of
    142      * the input array, or <code>Double.NaN</code> if the designated subarray
    143      * is empty.
    144      * <p>
    145      * Returns 0 for a single-value (i.e. length = 1) sample.
    146      * <p>
    147      * Throws <code>IllegalArgumentException</code> if the array is null.
    148      * <p>
    149      * Does not change the internal state of the statistic.
    150      *
    151      * @param values the input array
    152      * @param begin index of the first array element to include
    153      * @param length the number of elements to include
    154      * @return the standard deviation of the values or Double.NaN if length = 0
    155      * @throws IllegalArgumentException if the array is null or the array index
    156      *  parameters are not valid
    157      */
    158     public double evaluate(final double[] values, final int begin, final int length)  {
    159        return Math.sqrt(variance.evaluate(values, begin, length));
    160     }
    161
    162     /***
    163      * Returns the Standard Deviation of the entries in the specified portion of
    164      * the input array, using the precomputed mean value.  Returns
    165      * <code>Double.NaN</code> if the designated subarray is empty.
    166      * <p>
    167      * Returns 0 for a single-value (i.e. length = 1) sample.
    168      * <p>
    169      * The formula used assumes that the supplied mean value is the arithmetic
    170      * mean of the sample data, not a known population parameter.  This method
    171      * is supplied only to save computation when the mean has already been
    172      * computed.
    173      * <p>
    174      * Throws <code>IllegalArgumentException</code> if the array is null.
    175      * <p>
    176      * Does not change the internal state of the statistic.
    177      *
    178      * @param values the input array
    179      * @param mean the precomputed mean value
    180      * @param begin index of the first array element to include
    181      * @param length the number of elements to include
    182      * @return the standard deviation of the values or Double.NaN if length = 0
    183      * @throws IllegalArgumentException if the array is null or the array index
    184      *  parameters are not valid
    185      */
    186     public double evaluate(final double[] values, final double mean,
    187             final int begin, final int length)  {
    188         return Math.sqrt(variance.evaluate(values, mean, begin, length));
    189     }
    190
    191     /***
    192      * Returns the Standard Deviation of the entries in the input array, using
    193      * the precomputed mean value.  Returns
    194      * <code>Double.NaN</code> if the designated subarray is empty.
    195      * <p>
    196      * Returns 0 for a single-value (i.e. length = 1) sample.
    197      * <p>
    198      * The formula used assumes that the supplied mean value is the arithmetic
    199      * mean of the sample data, not a known population parameter.  This method
    200      * is supplied only to save computation when the mean has already been
    201      * computed.
    202      * <p>
    203      * Throws <code>IllegalArgumentException</code> if the array is null.
    204      * <p>
    205      * Does not change the internal state of the statistic.
    206      *
    207      * @param values the input array
    208      * @param mean the precomputed mean value
    209      * @return the standard deviation of the values or Double.NaN if length = 0
    210      * @throws IllegalArgumentException if the array is null
    211      */
    212     public double evaluate(final double[] values, final double mean)  {
    213         return Math.sqrt(variance.evaluate(values, mean));
    214     }
    215
    216     /***
    217      * @return Returns the isBiasCorrected.
    218      */
    219     public boolean isBiasCorrected() {
    220         return variance.isBiasCorrected();
    221     }
    222
    223     /***
    224      * @param isBiasCorrected The isBiasCorrected to set.
    225      */
    226     public void setBiasCorrected(boolean isBiasCorrected) {
    227         variance.setBiasCorrected(isBiasCorrected);
    228     }
    229 }