1 /* 2 * Copyright 2003-2004 The Apache Software Foundation. 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 package org.apache.commons.math.stat.descriptive.moment; 17 18 import java.io.Serializable; 19 20 import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic; 21 import org.apache.commons.math.stat.descriptive.summary.Sum; 22 23 /** 24 * Returns the arithmetic mean of the available values. Uses the definitional 25 * formula: 26 * <p> 27 * mean = sum(x_i) / n 28 * <p> 29 * where <code>n</code> is the number of observations. 30 * <p> 31 * The value of the statistic is computed using the following recursive 32 * updating algorithm: 33 * <p> 34 * <ol> 35 * <li>Initialize <code>m = </code> the first value</li> 36 * <li>For each additional value, update using <br> 37 * <code>m = m + (new value - m) / (number of observations)</code></li> 38 * </ol> 39 * <p> 40 * Returns <code>Double.NaN</code> if the dataset is empty. 41 * <p> 42 * <strong>Note that this implementation is not synchronized.</strong> If 43 * multiple threads access an instance of this class concurrently, and at least 44 * one of the threads invokes the <code>increment()</code> or 45 * <code>clear()</code> method, it must be synchronized externally. 46 * 47 * @version $Revision: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $ 48 */ 49 public class Mean extends AbstractStorelessUnivariateStatistic 50 implements Serializable { 51 52 /** Serializable version identifier */ 53 private static final long serialVersionUID = -1296043746617791564L; 54 55 /** First moment on which this statistic is based. */ 56 protected FirstMoment moment; 57 58 /** 59 * Determines whether or not this statistic can be incremented or cleared. 60 * <p> 61 * Statistics based on (constructed from) external moments cannot 62 * be incremented or cleared. 63 */ 64 protected boolean incMoment; 65 66 /** Constructs a Mean. */ 67 public Mean() { 68 incMoment = true; 69 moment = new FirstMoment(); 70 } 71 72 /** 73 * Constructs a Mean with an External Moment. 74 * 75 * @param m1 the moment 76 */ 77 public Mean(final FirstMoment m1) { 78 this.moment = m1; 79 incMoment = false; 80 } 81 82 /** 83 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double) 84 */ 85 public void increment(final double d) { 86 if (incMoment) { 87 moment.increment(d); 88 } 89 } 90 91 /** 92 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear() 93 */ 94 public void clear() { 95 if (incMoment) { 96 moment.clear(); 97 } 98 } 99 100 /** 101 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult() 102 */ 103 public double getResult() { 104 return moment.m1; 105 } 106 107 /** 108 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getN() 109 */ 110 public long getN() { 111 return moment.getN(); 112 } 113 114 /** 115 * Returns the arithmetic mean of the entries in the specified portion of 116 * the input array, or <code>Double.NaN</code> if the designated subarray 117 * is empty. 118 * <p> 119 * Throws <code>IllegalArgumentException</code> if the array is null. 120 * <p> 121 * See {@link Mean} for details on the computing algorithm. 122 * 123 * @param values the input array 124 * @param begin index of the first array element to include 125 * @param length the number of elements to include 126 * @return the mean of the values or Double.NaN if length = 0 127 * @throws IllegalArgumentException if the array is null or the array index 128 * parameters are not valid 129 */ 130 public double evaluate(final double[] values,final int begin, final int length) { 131 if (test(values, begin, length)) { 132 Sum sum = new Sum(); 133 return sum.evaluate(values, begin, length) / ((double) length); 134 } 135 return Double.NaN; 136 } 137 }