View Javadoc

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