KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > math > stat > descriptive > moment > StandardDeviation


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 JavaDoc;
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$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $
38  */

39 public class StandardDeviation extends AbstractStorelessUnivariateStatistic
40     implements Serializable JavaDoc {
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 }
Popular Tags