View Javadoc

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