← Back to branch summary

~ubuntu-branches/ubuntu/natty/commons-math/natty

« back to all changes in this revision

Viewing changes to src/main/java/org/apache/commons/math/stat/descriptive/moment/StandardDeviation.java

  • Committer: Bazaar Package Importer
  • Author(s): Damien Raude-Morvan
  • Date: 2009-08-22 01:13:25 UTC
  • mfrom: (1.1.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20090822011325-hi4peq1ua5weguwn
Tags: 2.0-1
* New upstream release.
* Set Maintainer field to Debian Java Team
* Add myself as Uploaders
* Switch to Quilt patch system:
  - Refresh all patchs
  - Remove B-D on dpatch, Add B-D on quilt
  - Include patchsys-quilt.mk in debian/rules
* Bump Standards-Version to 3.8.3:
  - Add a README.source to describe patch system
* Maven POMs:
  - Add a Build-Depends-Indep dependency on maven-repo-helper
  - Use mh_installpom and mh_installjar to install the POM and the jar to the
    Maven repository
* Use default-jdk/jre:
  - Depends on java5-runtime-headless
  - Build-Depends on default-jdk
  - Use /usr/lib/jvm/default-java as JAVA_HOME
* Move api documentation to /usr/share/doc/libcommons-math-java/api
* Build-Depends on junit4 instead of junit

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/main/java/org/apache/commons/math/stat/descriptive/moment/StandardDeviation.java
 
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
}