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: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $
38   */
39  public class StandardDeviation extends AbstractStorelessUnivariateStatistic
40      implements Serializable {
41  
42      /** Serializable version identifier */
43      private 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 }