View Javadoc

    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 }