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  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 </p>
26   * <p>
27   * where <code>n</code> is the number of observations. </p>
28   * <p>
29   * To limit numeric errors, the value of the statistic is computed using the
30   * following recursive updating algorithm: </p>
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></p>
37   * <p>
38   *  Returns <code>Double.NaN</code> if the dataset is empty.</p>
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.</p>
44   *
45   * @version $Revision: 780541 $ $Date: 2009-05-31 20:47:02 -0400 (Sun, 31 May 2009) $
46   */
47  public class FirstMoment extends AbstractStorelessUnivariateStatistic 
48      implements Serializable {
49  
50      /** Serializable version identifier */
51      private static final long serialVersionUID = 6112755307178490473L;
52  
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       * Copy constructor, creates a new {@code FirstMoment} identical
85       * to the {@code original}
86       * 
87       * @param original the {@code FirstMoment} instance to copy
88       */
89       public FirstMoment(FirstMoment original) {
90           super();
91           copy(original, this);
92       }
93      
94      /**
95       * {@inheritDoc}
96       */
97       @Override
98      public void increment(final double d) {
99          if (n == 0) {
100             m1 = 0.0;
101         }
102         n++;
103         double n0 = n;
104         dev = d - m1;
105         nDev = dev / n0;
106         m1 += nDev;
107     }
108 
109     /**
110      * {@inheritDoc}
111      */
112     @Override
113     public void clear() {
114         m1 = Double.NaN;
115         n = 0;
116         dev = Double.NaN;
117         nDev = Double.NaN;
118     }
119 
120     /**
121      * {@inheritDoc}
122      */
123     @Override
124     public double getResult() {
125         return m1;
126     }
127 
128     /**
129      * {@inheritDoc}
130      */
131     public long getN() {
132         return n;
133     }
134     
135     /**
136      * {@inheritDoc}
137      */
138     @Override
139     public FirstMoment copy() {
140         FirstMoment result = new FirstMoment();
141         copy(this, result);
142         return result; 
143     }
144      
145     /**
146      * Copies source to dest.
147      * <p>Neither source nor dest can be null.</p>
148      * 
149      * @param source FirstMoment to copy
150      * @param dest FirstMoment to copy to
151      * @throws NullPointerException if either source or dest is null
152      */
153     public static void copy(FirstMoment source, FirstMoment dest) {
154         dest.n = source.n;
155         dest.m1 = source.m1;
156         dest.dev = source.dev;
157         dest.nDev = dest.nDev;
158     }
159 }