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 }