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: 762116 $ $Date: 2009-04-05 12:48:53 -0400 (Sun, 05 Apr 2009) $
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       * Copy constructor, creates a new {@code StandardDeviation} identical
68       * to the {@code original}
69       * 
70       * @param original the {@code StandardDeviation} instance to copy
71       */
72      public StandardDeviation(StandardDeviation original) {
73          copy(original, this);
74      }
75      
76      /**
77       * Contructs a StandardDeviation with the specified value for the
78       * <code>isBiasCorrected</code> property.  If this property is set to 
79       * <code>true</code>, the {@link Variance} used in computing results will
80       * use the bias-corrected, or "sample" formula.  See {@link Variance} for
81       * details.
82       * 
83       * @param isBiasCorrected  whether or not the variance computation will use
84       * the bias-corrected formula
85       */
86      public StandardDeviation(boolean isBiasCorrected) {
87          variance = new Variance(isBiasCorrected);
88      }
89      
90      /**
91       * Contructs a StandardDeviation with the specified value for the
92       * <code>isBiasCorrected</code> property and the supplied external moment.
93       * If <code>isBiasCorrected</code> is set to <code>true</code>, the
94       * {@link Variance} used in computing results will use the bias-corrected,
95       * or "sample" formula.  See {@link Variance} for details.
96       * 
97       * @param isBiasCorrected  whether or not the variance computation will use
98       * the bias-corrected formula
99        * @param m2 the external moment
100      */
101     public StandardDeviation(boolean isBiasCorrected, SecondMoment m2) {
102         variance = new Variance(isBiasCorrected, m2);
103     }
104 
105     /**
106      * {@inheritDoc}
107      */
108     @Override
109     public void increment(final double d) {
110         variance.increment(d);
111     }
112     
113     /**
114      * {@inheritDoc}
115      */
116     public long getN() {
117         return variance.getN();
118     }
119 
120     /**
121      * {@inheritDoc}
122      */
123     @Override
124     public double getResult() {
125         return Math.sqrt(variance.getResult());
126     }
127 
128     /**
129      * {@inheritDoc}
130      */
131     @Override
132     public void clear() {
133         variance.clear();
134     }
135 
136     /**
137      * Returns the Standard Deviation of the entries in the input array, or 
138      * <code>Double.NaN</code> if the array is empty.
139      * <p>
140      * Returns 0 for a single-value (i.e. length = 1) sample.</p>
141      * <p>
142      * Throws <code>IllegalArgumentException</code> if the array is null.</p>
143      * <p>
144      * Does not change the internal state of the statistic.</p>
145      * 
146      * @param values the input array
147      * @return the standard deviation of the values or Double.NaN if length = 0
148      * @throws IllegalArgumentException if the array is null
149      */  
150     @Override
151     public double evaluate(final double[] values)  {
152         return Math.sqrt(variance.evaluate(values));
153     }
154     
155     /**
156      * Returns the Standard Deviation of the entries in the specified portion of
157      * the input array, or <code>Double.NaN</code> if the designated subarray
158      * is empty.
159      * <p>
160      * Returns 0 for a single-value (i.e. length = 1) sample. </p>
161      * <p>
162      * Throws <code>IllegalArgumentException</code> if the array is null.</p>
163      * <p>
164      * Does not change the internal state of the statistic.</p>
165      * 
166      * @param values the input array
167      * @param begin index of the first array element to include
168      * @param length the number of elements to include
169      * @return the standard deviation of the values or Double.NaN if length = 0
170      * @throws IllegalArgumentException if the array is null or the array index
171      *  parameters are not valid
172      */
173     @Override
174     public double evaluate(final double[] values, final int begin, final int length)  {
175        return Math.sqrt(variance.evaluate(values, begin, length));
176     }
177     
178     /**
179      * Returns the Standard Deviation of the entries in the specified portion of
180      * the input array, using the precomputed mean value.  Returns
181      * <code>Double.NaN</code> if the designated subarray is empty.
182      * <p>
183      * Returns 0 for a single-value (i.e. length = 1) sample.</p>
184      * <p>
185      * The formula used assumes that the supplied mean value is the arithmetic
186      * mean of the sample data, not a known population parameter.  This method
187      * is supplied only to save computation when the mean has already been
188      * computed.</p>
189      * <p>
190      * Throws <code>IllegalArgumentException</code> if the array is null.</p>
191      * <p>
192      * Does not change the internal state of the statistic.</p>
193      * 
194      * @param values the input array
195      * @param mean the precomputed mean value
196      * @param begin index of the first array element to include
197      * @param length the number of elements to include
198      * @return the standard deviation of the values or Double.NaN if length = 0
199      * @throws IllegalArgumentException if the array is null or the array index
200      *  parameters are not valid
201      */
202     public double evaluate(final double[] values, final double mean,
203             final int begin, final int length)  {
204         return Math.sqrt(variance.evaluate(values, mean, begin, length));
205     }
206     
207     /**
208      * Returns the Standard Deviation of the entries in the input array, using
209      * the precomputed mean value.  Returns
210      * <code>Double.NaN</code> if the designated subarray is empty.
211      * <p>
212      * Returns 0 for a single-value (i.e. length = 1) sample.</p>
213      * <p>
214      * The formula used assumes that the supplied mean value is the arithmetic
215      * mean of the sample data, not a known population parameter.  This method
216      * is supplied only to save computation when the mean has already been
217      * computed.</p>
218      * <p>
219      * Throws <code>IllegalArgumentException</code> if the array is null.</p>
220      * <p>
221      * Does not change the internal state of the statistic.</p>
222      * 
223      * @param values the input array
224      * @param mean the precomputed mean value
225      * @return the standard deviation of the values or Double.NaN if length = 0
226      * @throws IllegalArgumentException if the array is null
227      */
228     public double evaluate(final double[] values, final double mean)  {
229         return Math.sqrt(variance.evaluate(values, mean));
230     }
231     
232     /**
233      * @return Returns the isBiasCorrected.
234      */
235     public boolean isBiasCorrected() {
236         return variance.isBiasCorrected();
237     }
238 
239     /**
240      * @param isBiasCorrected The isBiasCorrected to set.
241      */
242     public void setBiasCorrected(boolean isBiasCorrected) {
243         variance.setBiasCorrected(isBiasCorrected);
244     }
245     
246     /**
247      * {@inheritDoc}
248      */
249     @Override
250     public StandardDeviation copy() {
251         StandardDeviation result = new StandardDeviation();
252         copy(this, result);
253         return result;
254     }
255     
256     
257     /**
258      * Copies source to dest.
259      * <p>Neither source nor dest can be null.</p>
260      * 
261      * @param source StandardDeviation to copy
262      * @param dest StandardDeviation to copy to
263      * @throws NullPointerException if either source or dest is null
264      */
265     public static void copy(StandardDeviation source, StandardDeviation dest) {
266         dest.variance = source.variance.copy();
267     }
268     
269 }