1
2
3
4
5
6
7
8
9
10
11
12
13
14
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: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $
48 */
49 public class Mean extends AbstractStorelessUnivariateStatistic
50 implements Serializable {
51
52 /** Serializable version identifier */
53 private 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 }