001: /*
002: * Copyright 2003-2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.apache.commons.math.stat.descriptive.moment;
017:
018: import java.io.Serializable;
019:
020: import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
021:
022: /**
023: * Computes the sample standard deviation. The standard deviation
024: * is the positive square root of the variance. This implementation wraps a
025: * {@link Variance} instance. The <code>isBiasCorrected</code> property of the
026: * wrapped Variance instance is exposed, so that this class can be used to
027: * compute both the "sample standard deviation" (the square root of the
028: * bias-corrected "sample variance") or the "population standard deviation"
029: * (the square root of the non-bias-corrected "population variance"). See
030: * {@link Variance} for more information.
031: * <p>
032: * <strong>Note that this implementation is not synchronized.</strong> If
033: * multiple threads access an instance of this class concurrently, and at least
034: * one of the threads invokes the <code>increment()</code> or
035: * <code>clear()</code> method, it must be synchronized externally.
036: *
037: * @version $Revision: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $
038: */
039: public class StandardDeviation extends
040: AbstractStorelessUnivariateStatistic implements Serializable {
041:
042: /** Serializable version identifier */
043: private static final long serialVersionUID = 5728716329662425188L;
044:
045: /** Wrapped Variance instance */
046: private Variance variance = null;
047:
048: /**
049: * Constructs a StandardDeviation. Sets the underlying {@link Variance}
050: * instance's <code>isBiasCorrected</code> property to true.
051: */
052: public StandardDeviation() {
053: variance = new Variance();
054: }
055:
056: /**
057: * Constructs a StandardDeviation from an external second moment.
058: *
059: * @param m2 the external moment
060: */
061: public StandardDeviation(final SecondMoment m2) {
062: variance = new Variance(m2);
063: }
064:
065: /**
066: * Contructs a StandardDeviation with the specified value for the
067: * <code>isBiasCorrected</code> property. If this property is set to
068: * <code>true</code>, the {@link Variance} used in computing results will
069: * use the bias-corrected, or "sample" formula. See {@link Variance} for
070: * details.
071: *
072: * @param isBiasCorrected whether or not the variance computation will use
073: * the bias-corrected formula
074: */
075: public StandardDeviation(boolean isBiasCorrected) {
076: variance = new Variance(isBiasCorrected);
077: }
078:
079: /**
080: * Contructs a StandardDeviation with the specified value for the
081: * <code>isBiasCorrected</code> property and the supplied external moment.
082: * If <code>isBiasCorrected</code> is set to <code>true</code>, the
083: * {@link Variance} used in computing results will use the bias-corrected,
084: * or "sample" formula. See {@link Variance} for details.
085: *
086: * @param isBiasCorrected whether or not the variance computation will use
087: * the bias-corrected formula
088: * @param m2 the external moment
089: */
090: public StandardDeviation(boolean isBiasCorrected, SecondMoment m2) {
091: variance = new Variance(isBiasCorrected, m2);
092: }
093:
094: /**
095: * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
096: */
097: public void increment(final double d) {
098: variance.increment(d);
099: }
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,
159: 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.
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.
174: * <p>
175: * Throws <code>IllegalArgumentException</code> if the array is null.
176: * <p>
177: * Does not change the internal state of the statistic.
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
190: .sqrt(variance.evaluate(values, mean, begin, length));
191: }
192:
193: /**
194: * Returns the Standard Deviation of the entries in the input array, using
195: * the precomputed mean value. Returns
196: * <code>Double.NaN</code> if the designated subarray is empty.
197: * <p>
198: * Returns 0 for a single-value (i.e. length = 1) sample.
199: * <p>
200: * The formula used assumes that the supplied mean value is the arithmetic
201: * mean of the sample data, not a known population parameter. This method
202: * is supplied only to save computation when the mean has already been
203: * computed.
204: * <p>
205: * Throws <code>IllegalArgumentException</code> if the array is null.
206: * <p>
207: * Does not change the internal state of the statistic.
208: *
209: * @param values the input array
210: * @param mean the precomputed mean value
211: * @return the standard deviation of the values or Double.NaN if length = 0
212: * @throws IllegalArgumentException if the array is null
213: */
214: public double evaluate(final double[] values, final double mean) {
215: return Math.sqrt(variance.evaluate(values, mean));
216: }
217:
218: /**
219: * @return Returns the isBiasCorrected.
220: */
221: public boolean isBiasCorrected() {
222: return variance.isBiasCorrected();
223: }
224:
225: /**
226: * @param isBiasCorrected The isBiasCorrected to set.
227: */
228: public void setBiasCorrected(boolean isBiasCorrected) {
229: variance.setBiasCorrected(isBiasCorrected);
230: }
231: }
|