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 }