Classes in this File | Line Coverage | Branch Coverage | Complexity | |||||||
StandardDeviation |
|
| 1.0;1 |
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$ $Date: 2005-02-26 05:11:52 -0800 (Sat, 26 Feb 2005) $ |
|
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 | 24 | 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 | 20 | public StandardDeviation() { |
53 | 20 | variance = new Variance(); |
54 | 20 | } |
55 | ||
56 | /** |
|
57 | * Constructs a StandardDeviation from an external second moment. |
|
58 | * |
|
59 | * @param m2 the external moment |
|
60 | */ |
|
61 | 0 | public StandardDeviation(final SecondMoment m2) { |
62 | 0 | variance = new Variance(m2); |
63 | 0 | } |
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 | 2 | public StandardDeviation(boolean isBiasCorrected) { |
76 | 2 | variance = new Variance(isBiasCorrected); |
77 | 2 | } |
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 | 2 | public StandardDeviation(boolean isBiasCorrected, SecondMoment m2) { |
91 | 2 | variance = new Variance(isBiasCorrected, m2); |
92 | 2 | } |
93 | ||
94 | /** |
|
95 | * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double) |
|
96 | */ |
|
97 | public void increment(final double d) { |
|
98 | 196 | variance.increment(d); |
99 | 196 | } |
100 | ||
101 | /** |
|
102 | * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getN() |
|
103 | */ |
|
104 | public long getN() { |
|
105 | 58 | return variance.getN(); |
106 | } |
|
107 | ||
108 | /** |
|
109 | * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult() |
|
110 | */ |
|
111 | public double getResult() { |
|
112 | 100 | return Math.sqrt(variance.getResult()); |
113 | } |
|
114 | ||
115 | /** |
|
116 | * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear() |
|
117 | */ |
|
118 | public void clear() { |
|
119 | 22 | variance.clear(); |
120 | 22 | } |
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 | 18 | 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 | 0 | 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 | 0 | 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 | 0 | return Math.sqrt(variance.evaluate(values, mean)); |
214 | } |
|
215 | ||
216 | /** |
|
217 | * @return Returns the isBiasCorrected. |
|
218 | */ |
|
219 | public boolean isBiasCorrected() { |
|
220 | 0 | return variance.isBiasCorrected(); |
221 | } |
|
222 | ||
223 | /** |
|
224 | * @param isBiasCorrected The isBiasCorrected to set. |
|
225 | */ |
|
226 | public void setBiasCorrected(boolean isBiasCorrected) { |
|
227 | 2 | variance.setBiasCorrected(isBiasCorrected); |
228 | 2 | } |
229 | } |