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 }