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 }