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: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $ 38 */ 39 public class StandardDeviation extends AbstractStorelessUnivariateStatistic 40 implements Serializable { 41 42 /** Serializable version identifier */ 43 private 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 }