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 22 /** 23 * Computes the first moment (arithmetic mean). Uses the definitional formula: 24 * <p> 25 * mean = sum(x_i) / n 26 * <p> 27 * where <code>n</code> is the number of observations. 28 * <p> 29 * To limit numeric errors, the value of the statistic is computed using the 30 * following recursive updating algorithm: 31 * <p> 32 * <ol> 33 * <li>Initialize <code>m = </code> the first value</li> 34 * <li>For each additional value, update using <br> 35 * <code>m = m + (new value - m) / (number of observations)</code></li> 36 * </ol> 37 * <p> 38 * Returns <code>Double.NaN</code> if the dataset is empty. 39 * <p> 40 * <strong>Note that this implementation is not synchronized.</strong> If 41 * multiple threads access an instance of this class concurrently, and at least 42 * one of the threads invokes the <code>increment()</code> or 43 * <code>clear()</code> method, it must be synchronized externally. 44 * 45 * @version $Revision: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $ 46 */ 47 public class FirstMoment extends AbstractStorelessUnivariateStatistic 48 implements Serializable { 49 50 /** Serializable version identifier */ 51 private static final long serialVersionUID = -803343206421984070L; 52 53 /** Count of values that have been added */ 54 protected long n; 55 56 /** First moment of values that have been added */ 57 protected double m1; 58 59 /** 60 * Deviation of most recently added value from previous first moment. 61 * Retained to prevent repeated computation in higher order moments. 62 */ 63 protected double dev; 64 65 /** 66 * Deviation of most recently added value from previous first moment, 67 * normalized by previous sample size. Retained to prevent repeated 68 * computation in higher order moments 69 */ 70 protected double nDev; 71 72 /** 73 * Create a FirstMoment instance 74 */ 75 public FirstMoment() { 76 n = 0; 77 m1 = Double.NaN; 78 dev = Double.NaN; 79 nDev = Double.NaN; 80 } 81 82 /** 83 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double) 84 */ 85 public void increment(final double d) { 86 if (n == 0) { 87 m1 = 0.0; 88 } 89 n++; 90 double n0 = (double) n; 91 dev = d - m1; 92 nDev = dev / n0; 93 m1 += nDev; 94 } 95 96 /** 97 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear() 98 */ 99 public void clear() { 100 m1 = Double.NaN; 101 n = 0; 102 dev = Double.NaN; 103 nDev = Double.NaN; 104 } 105 106 /** 107 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult() 108 */ 109 public double getResult() { 110 return m1; 111 } 112 113 /** 114 * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getN() 115 */ 116 public long getN() { 117 return n; 118 } 119 }