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  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: 1.1 $ $Date: 2004/10/08 05:08:17 $
    48   */
    49  public class Mean extends AbstractStorelessUnivariateStatistic
    50      implements Serializable {
    51
    52      /*** Serializable version identifier */
    53      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 }