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 */ 017package org.apache.commons.math4.legacy.stat.descriptive.moment; 018 019import org.apache.commons.math4.legacy.exception.MathIllegalArgumentException; 020import org.apache.commons.math4.legacy.exception.NullArgumentException; 021import org.apache.commons.math4.legacy.stat.descriptive.AbstractStorelessUnivariateStatistic; 022import org.apache.commons.math4.legacy.stat.descriptive.WeightedEvaluation; 023import org.apache.commons.math4.legacy.stat.descriptive.summary.Sum; 024import org.apache.commons.math4.legacy.core.MathArrays; 025 026/** 027 * Computes the arithmetic mean of a set of values. Uses the definitional 028 * formula: 029 * <p> 030 * mean = sum(x_i) / n 031 * </p> 032 * <p>where <code>n</code> is the number of observations. 033 * </p> 034 * <p>When {@link #increment(double)} is used to add data incrementally from a 035 * stream of (unstored) values, the value of the statistic that 036 * {@link #getResult()} returns is computed using the following recursive 037 * updating algorithm: </p> 038 * <ol> 039 * <li>Initialize <code>m = </code> the first value</li> 040 * <li>For each additional value, update using <br> 041 * <code>m = m + (new value - m) / (number of observations)</code></li> 042 * </ol> 043 * <p> If {@link #evaluate(double[])} is used to compute the mean of an array 044 * of stored values, a two-pass, corrected algorithm is used, starting with 045 * the definitional formula computed using the array of stored values and then 046 * correcting this by adding the mean deviation of the data values from the 047 * arithmetic mean. See, e.g. "Comparison of Several Algorithms for Computing 048 * Sample Means and Variances," Robert F. Ling, Journal of the American 049 * Statistical Association, Vol. 69, No. 348 (Dec., 1974), pp. 859-866. </p> 050 * <p> 051 * Returns <code>Double.NaN</code> if the dataset is empty. Note that 052 * Double.NaN may also be returned if the input includes NaN and / or infinite 053 * values. 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 */ 060public class Mean extends AbstractStorelessUnivariateStatistic 061 implements WeightedEvaluation { 062 /** First moment on which this statistic is based. */ 063 protected FirstMoment moment; 064 065 /** 066 * Determines whether or not this statistic can be incremented or cleared. 067 * <p> 068 * Statistics based on (constructed from) external moments cannot 069 * be incremented or cleared.</p> 070 */ 071 protected boolean incMoment; 072 073 /** Constructs a Mean. */ 074 public Mean() { 075 incMoment = true; 076 moment = new FirstMoment(); 077 } 078 079 /** 080 * Constructs a Mean with an External Moment. 081 * 082 * @param m1 the moment 083 */ 084 public Mean(final FirstMoment m1) { 085 this.moment = m1; 086 incMoment = false; 087 } 088 089 /** 090 * Copy constructor, creates a new {@code Mean} identical 091 * to the {@code original}. 092 * 093 * @param original the {@code Mean} instance to copy 094 * @throws NullArgumentException if original is null 095 */ 096 public Mean(Mean original) throws NullArgumentException { 097 copy(original, this); 098 } 099 100 /** 101 * {@inheritDoc} 102 * <p>Note that when {@link #Mean(FirstMoment)} is used to 103 * create a Mean, this method does nothing. In that case, the 104 * FirstMoment should be incremented directly.</p> 105 */ 106 @Override 107 public void increment(final double d) { 108 if (incMoment) { 109 moment.increment(d); 110 } 111 } 112 113 /** 114 * {@inheritDoc} 115 */ 116 @Override 117 public void clear() { 118 if (incMoment) { 119 moment.clear(); 120 } 121 } 122 123 /** 124 * {@inheritDoc} 125 */ 126 @Override 127 public double getResult() { 128 return moment.m1; 129 } 130 131 /** 132 * {@inheritDoc} 133 */ 134 @Override 135 public long getN() { 136 return moment.getN(); 137 } 138 139 /** 140 * Returns the arithmetic mean of the entries in the specified portion of 141 * the input array, or <code>Double.NaN</code> if the designated subarray 142 * is empty. 143 * <p> 144 * Throws <code>IllegalArgumentException</code> if the array is null.</p> 145 * <p> 146 * See {@link Mean} for details on the computing algorithm.</p> 147 * 148 * @param values the input array 149 * @param begin index of the first array element to include 150 * @param length the number of elements to include 151 * @return the mean of the values or Double.NaN if length = 0 152 * @throws MathIllegalArgumentException if the array is null or the array index 153 * parameters are not valid 154 */ 155 @Override 156 public double evaluate(final double[] values, final int begin, final int length) 157 throws MathIllegalArgumentException { 158 159 if (MathArrays.verifyValues(values, begin, length)) { 160 Sum sum = new Sum(); 161 double sampleSize = length; 162 163 // Compute initial estimate using definitional formula 164 double xbar = sum.evaluate(values, begin, length) / sampleSize; 165 166 // Compute correction factor in second pass 167 double correction = 0; 168 for (int i = begin; i < begin + length; i++) { 169 correction += values[i] - xbar; 170 } 171 return xbar + (correction/sampleSize); 172 } 173 return Double.NaN; 174 } 175 176 /** 177 * Returns the weighted arithmetic mean of the entries in the specified portion of 178 * the input array, or <code>Double.NaN</code> if the designated subarray 179 * is empty. 180 * <p> 181 * Throws <code>IllegalArgumentException</code> if either array is null.</p> 182 * <p> 183 * See {@link Mean} for details on the computing algorithm. The two-pass algorithm 184 * described above is used here, with weights applied in computing both the original 185 * estimate and the correction factor.</p> 186 * <p> 187 * Throws <code>IllegalArgumentException</code> if any of the following are true: 188 * <ul><li>the values array is null</li> 189 * <li>the weights array is null</li> 190 * <li>the weights array does not have the same length as the values array</li> 191 * <li>the weights array contains one or more infinite values</li> 192 * <li>the weights array contains one or more NaN values</li> 193 * <li>the weights array contains negative values</li> 194 * <li>the start and length arguments do not determine a valid array</li> 195 * </ul> 196 * 197 * @param values the input array 198 * @param weights the weights array 199 * @param begin index of the first array element to include 200 * @param length the number of elements to include 201 * @return the mean of the values or Double.NaN if length = 0 202 * @throws MathIllegalArgumentException if the parameters are not valid 203 * @since 2.1 204 */ 205 @Override 206 public double evaluate(final double[] values, final double[] weights, 207 final int begin, final int length) throws MathIllegalArgumentException { 208 if (MathArrays.verifyValues(values, weights, begin, length)) { 209 Sum sum = new Sum(); 210 211 // Compute initial estimate using definitional formula 212 double sumw = sum.evaluate(weights,begin,length); 213 double xbarw = sum.evaluate(values, weights, begin, length) / sumw; 214 215 // Compute correction factor in second pass 216 double correction = 0; 217 for (int i = begin; i < begin + length; i++) { 218 correction += weights[i] * (values[i] - xbarw); 219 } 220 return xbarw + (correction/sumw); 221 } 222 return Double.NaN; 223 } 224 225 /** 226 * Returns the weighted arithmetic mean of the entries in the input array. 227 * <p> 228 * Throws <code>MathIllegalArgumentException</code> if either array is null.</p> 229 * <p> 230 * See {@link Mean} for details on the computing algorithm. The two-pass algorithm 231 * described above is used here, with weights applied in computing both the original 232 * estimate and the correction factor.</p> 233 * <p> 234 * Throws <code>MathIllegalArgumentException</code> if any of the following are true: 235 * <ul><li>the values array is null</li> 236 * <li>the weights array is null</li> 237 * <li>the weights array does not have the same length as the values array</li> 238 * <li>the weights array contains one or more infinite values</li> 239 * <li>the weights array contains one or more NaN values</li> 240 * <li>the weights array contains negative values</li> 241 * </ul> 242 * 243 * @param values the input array 244 * @param weights the weights array 245 * @return the mean of the values or Double.NaN if length = 0 246 * @throws MathIllegalArgumentException if the parameters are not valid 247 * @since 2.1 248 */ 249 @Override 250 public double evaluate(final double[] values, final double[] weights) 251 throws MathIllegalArgumentException { 252 return evaluate(values, weights, 0, values.length); 253 } 254 255 /** 256 * {@inheritDoc} 257 */ 258 @Override 259 public Mean copy() { 260 Mean result = new Mean(); 261 // No try-catch or advertised exception because args are guaranteed non-null 262 copy(this, result); 263 return result; 264 } 265 266 /** 267 * Copies source to dest. 268 * <p>Neither source nor dest can be null.</p> 269 * 270 * @param source Mean to copy 271 * @param dest Mean to copy to 272 * @throws NullArgumentException if either source or dest is null 273 */ 274 public static void copy(Mean source, Mean dest) 275 throws NullArgumentException { 276 NullArgumentException.check(source); 277 NullArgumentException.check(dest); 278 dest.incMoment = source.incMoment; 279 dest.moment = source.moment.copy(); 280 } 281}