001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math3.stat.descriptive.moment;
018
019 import java.io.Serializable;
020
021 import org.apache.commons.math3.exception.MathIllegalArgumentException;
022 import org.apache.commons.math3.exception.NullArgumentException;
023 import org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic;
024 import org.apache.commons.math3.stat.descriptive.WeightedEvaluation;
025 import org.apache.commons.math3.stat.descriptive.summary.Sum;
026 import org.apache.commons.math3.util.MathUtils;
027
028 /**
029 * <p>Computes the arithmetic mean of a set of values. Uses the definitional
030 * formula:</p>
031 * <p>
032 * mean = sum(x_i) / n
033 * </p>
034 * <p>where <code>n</code> is the number of observations.
035 * </p>
036 * <p>When {@link #increment(double)} is used to add data incrementally from a
037 * stream of (unstored) values, the value of the statistic that
038 * {@link #getResult()} returns is computed using the following recursive
039 * updating algorithm: </p>
040 * <ol>
041 * <li>Initialize <code>m = </code> the first value</li>
042 * <li>For each additional value, update using <br>
043 * <code>m = m + (new value - m) / (number of observations)</code></li>
044 * </ol>
045 * <p> If {@link #evaluate(double[])} is used to compute the mean of an array
046 * of stored values, a two-pass, corrected algorithm is used, starting with
047 * the definitional formula computed using the array of stored values and then
048 * correcting this by adding the mean deviation of the data values from the
049 * arithmetic mean. See, e.g. "Comparison of Several Algorithms for Computing
050 * Sample Means and Variances," Robert F. Ling, Journal of the American
051 * Statistical Association, Vol. 69, No. 348 (Dec., 1974), pp. 859-866. </p>
052 * <p>
053 * Returns <code>Double.NaN</code> if the dataset is empty.
054 * </p>
055 * <strong>Note that this implementation is not synchronized.</strong> If
056 * multiple threads access an instance of this class concurrently, and at least
057 * one of the threads invokes the <code>increment()</code> or
058 * <code>clear()</code> method, it must be synchronized externally.
059 *
060 * @version $Id: Mean.java 1416643 2012-12-03 19:37:14Z tn $
061 */
062 public class Mean extends AbstractStorelessUnivariateStatistic
063 implements Serializable, WeightedEvaluation {
064
065 /** Serializable version identifier */
066 private static final long serialVersionUID = -1296043746617791564L;
067
068 /** First moment on which this statistic is based. */
069 protected FirstMoment moment;
070
071 /**
072 * Determines whether or not this statistic can be incremented or cleared.
073 * <p>
074 * Statistics based on (constructed from) external moments cannot
075 * be incremented or cleared.</p>
076 */
077 protected boolean incMoment;
078
079 /** Constructs a Mean. */
080 public Mean() {
081 incMoment = true;
082 moment = new FirstMoment();
083 }
084
085 /**
086 * Constructs a Mean with an External Moment.
087 *
088 * @param m1 the moment
089 */
090 public Mean(final FirstMoment m1) {
091 this.moment = m1;
092 incMoment = false;
093 }
094
095 /**
096 * Copy constructor, creates a new {@code Mean} identical
097 * to the {@code original}
098 *
099 * @param original the {@code Mean} instance to copy
100 * @throws NullArgumentException if original is null
101 */
102 public Mean(Mean original) throws NullArgumentException {
103 copy(original, this);
104 }
105
106 /**
107 * {@inheritDoc}
108 * <p>Note that when {@link #Mean(FirstMoment)} is used to
109 * create a Mean, this method does nothing. In that case, the
110 * FirstMoment should be incremented directly.</p>
111 */
112 @Override
113 public void increment(final double d) {
114 if (incMoment) {
115 moment.increment(d);
116 }
117 }
118
119 /**
120 * {@inheritDoc}
121 */
122 @Override
123 public void clear() {
124 if (incMoment) {
125 moment.clear();
126 }
127 }
128
129 /**
130 * {@inheritDoc}
131 */
132 @Override
133 public double getResult() {
134 return moment.m1;
135 }
136
137 /**
138 * {@inheritDoc}
139 */
140 public long getN() {
141 return moment.getN();
142 }
143
144 /**
145 * Returns the arithmetic mean of the entries in the specified portion of
146 * the input array, or <code>Double.NaN</code> if the designated subarray
147 * is empty.
148 * <p>
149 * Throws <code>IllegalArgumentException</code> if the array is null.</p>
150 * <p>
151 * See {@link Mean} for details on the computing algorithm.</p>
152 *
153 * @param values the input array
154 * @param begin index of the first array element to include
155 * @param length the number of elements to include
156 * @return the mean of the values or Double.NaN if length = 0
157 * @throws MathIllegalArgumentException if the array is null or the array index
158 * parameters are not valid
159 */
160 @Override
161 public double evaluate(final double[] values,final int begin, final int length)
162 throws MathIllegalArgumentException {
163 if (test(values, begin, length)) {
164 Sum sum = new Sum();
165 double sampleSize = length;
166
167 // Compute initial estimate using definitional formula
168 double xbar = sum.evaluate(values, begin, length) / sampleSize;
169
170 // Compute correction factor in second pass
171 double correction = 0;
172 for (int i = begin; i < begin + length; i++) {
173 correction += values[i] - xbar;
174 }
175 return xbar + (correction/sampleSize);
176 }
177 return Double.NaN;
178 }
179
180 /**
181 * Returns the weighted arithmetic mean of the entries in the specified portion of
182 * the input array, or <code>Double.NaN</code> if the designated subarray
183 * is empty.
184 * <p>
185 * Throws <code>IllegalArgumentException</code> if either array is null.</p>
186 * <p>
187 * See {@link Mean} for details on the computing algorithm. The two-pass algorithm
188 * described above is used here, with weights applied in computing both the original
189 * estimate and the correction factor.</p>
190 * <p>
191 * Throws <code>IllegalArgumentException</code> if any of the following are true:
192 * <ul><li>the values array is null</li>
193 * <li>the weights array is null</li>
194 * <li>the weights array does not have the same length as the values array</li>
195 * <li>the weights array contains one or more infinite values</li>
196 * <li>the weights array contains one or more NaN values</li>
197 * <li>the weights array contains negative values</li>
198 * <li>the start and length arguments do not determine a valid array</li>
199 * </ul></p>
200 *
201 * @param values the input array
202 * @param weights the weights array
203 * @param begin index of the first array element to include
204 * @param length the number of elements to include
205 * @return the mean of the values or Double.NaN if length = 0
206 * @throws MathIllegalArgumentException if the parameters are not valid
207 * @since 2.1
208 */
209 public double evaluate(final double[] values, final double[] weights,
210 final int begin, final int length) throws MathIllegalArgumentException {
211 if (test(values, weights, begin, length)) {
212 Sum sum = new Sum();
213
214 // Compute initial estimate using definitional formula
215 double sumw = sum.evaluate(weights,begin,length);
216 double xbarw = sum.evaluate(values, weights, begin, length) / sumw;
217
218 // Compute correction factor in second pass
219 double correction = 0;
220 for (int i = begin; i < begin + length; i++) {
221 correction += weights[i] * (values[i] - xbarw);
222 }
223 return xbarw + (correction/sumw);
224 }
225 return Double.NaN;
226 }
227
228 /**
229 * Returns the weighted arithmetic mean of the entries in the input array.
230 * <p>
231 * Throws <code>MathIllegalArgumentException</code> if either array is null.</p>
232 * <p>
233 * See {@link Mean} for details on the computing algorithm. The two-pass algorithm
234 * described above is used here, with weights applied in computing both the original
235 * estimate and the correction factor.</p>
236 * <p>
237 * Throws <code>MathIllegalArgumentException</code> if any of the following are true:
238 * <ul><li>the values array is null</li>
239 * <li>the weights array is null</li>
240 * <li>the weights array does not have the same length as the values array</li>
241 * <li>the weights array contains one or more infinite values</li>
242 * <li>the weights array contains one or more NaN values</li>
243 * <li>the weights array contains negative values</li>
244 * </ul></p>
245 *
246 * @param values the input array
247 * @param weights the weights array
248 * @return the mean of the values or Double.NaN if length = 0
249 * @throws MathIllegalArgumentException if the parameters are not valid
250 * @since 2.1
251 */
252 public double evaluate(final double[] values, final double[] weights)
253 throws MathIllegalArgumentException {
254 return evaluate(values, weights, 0, values.length);
255 }
256
257 /**
258 * {@inheritDoc}
259 */
260 @Override
261 public Mean copy() {
262 Mean result = new Mean();
263 // No try-catch or advertised exception because args are guaranteed non-null
264 copy(this, result);
265 return result;
266 }
267
268
269 /**
270 * Copies source to dest.
271 * <p>Neither source nor dest can be null.</p>
272 *
273 * @param source Mean to copy
274 * @param dest Mean to copy to
275 * @throws NullArgumentException if either source or dest is null
276 */
277 public static void copy(Mean source, Mean dest)
278 throws NullArgumentException {
279 MathUtils.checkNotNull(source);
280 MathUtils.checkNotNull(dest);
281 dest.setData(source.getDataRef());
282 dest.incMoment = source.incMoment;
283 dest.moment = source.moment.copy();
284 }
285 }