Mean.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-1.5.0).
003  * Copyright (c) 2007-2013 Franz Wilhelmstötter
004  *
005  * Licensed under the Apache License, Version 2.0 (the "License");
006  * you may not use this file except in compliance with the License.
007  * You may obtain a copy of the License at
008  *
009  *      http://www.apache.org/licenses/LICENSE-2.0
010  *
011  * Unless required by applicable law or agreed to in writing, software
012  * distributed under the License is distributed on an "AS IS" BASIS,
013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014  * See the License for the specific language governing permissions and
015  * limitations under the License.
016  *
017  * Author:
018  *    Franz Wilhelmstötter (franz.wilhelmstoetter@gmx.at)
019  */
020 package org.jenetics.stat;
021 
022 import static java.lang.String.format;
023 import static org.jenetics.util.object.eq;
024 import static org.jenetics.util.object.hashCodeOf;
025 
026 import org.jenetics.util.MappedAccumulator;
027 
028 
029 /**
030  <p>Calculate  the Arithmetic mean from a finite sample of <i>N</i>
031  * observations.</p>
032  <p><img src="doc-files/arithmetic-mean.gif"
033  *         alt="\bar{x}=\frac{1}{N}\sum_{i=1}^{N}x_i"
034  *    />
035  </p>
036  *
037  <p/>
038  <strong>Note that this implementation is not synchronized.</strong> If
039  * multiple threads access this object concurrently, and at least one of the
040  * threads modifies it, it must be synchronized externally.
041  *
042  @see <a href="http://mathworld.wolfram.com/ArithmeticMean.html">Wolfram MathWorld: Artithmetic Mean</a>
043  @see <a href="http://en.wikipedia.org/wiki/Arithmetic_mean">Wikipedia: Arithmetic Mean</a>
044  *
045  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
046  @since 1.0
047  @version 1.0 &mdash; <em>$Date: 2013-09-01 $</em>
048  */
049 public class Mean<N extends Number> extends MappedAccumulator<N> {
050 
051     protected double _mean = Double.NaN;
052 
053     public Mean() {
054     }
055 
056     /**
057      * Return the mean value of the accumulated values.
058      *
059      @return the mean value of the accumulated values, or {@link java.lang.Double#NaN}
060      *          if {@code getSamples() == 0}.
061      */
062     public double getMean() {
063         return _mean;
064     }
065 
066     /**
067      * Return the
068      * <a href="https://secure.wikimedia.org/wikipedia/en/wiki/Standard_error_%28statistics%29">
069      * Standard error
070      </a> of the calculated mean.
071      *
072      @return the standard error of the calculated mean.
073      */
074     public double getStandardError() {
075         double sem = Double.NaN;
076 
077         if (_samples > 0) {
078             sem = _mean/Math.sqrt(_samples);
079         }
080 
081         return sem;
082     }
083 
084     /**
085      @throws NullPointerException if the given {@code value} is {@code null}.
086      */
087     @Override
088     public void accumulate(final N value) {
089         if (_samples == 0) {
090             _mean = 0;
091         }
092 
093         _mean += (value.doubleValue() - _mean)/(++_samples);
094     }
095 
096     @Override
097     public int hashCode() {
098         return hashCodeOf(getClass()).and(super.hashCode()).and(_mean).value();
099     }
100 
101     @Override
102     public boolean equals(final Object obj) {
103         if (obj == this) {
104             return true;
105         }
106         if (obj == null || getClass() != obj.getClass()) {
107             return false;
108         }
109 
110         final Mean<?> mean = (Mean<?>)obj;
111         return eq(_mean, mean._mean&& super.equals(mean);
112     }
113 
114     @Override
115     public String toString() {
116         return format(
117             "%s[samples=%d, mean=%f, stderr=%f]",
118             getClass().getSimpleName(),
119             getSamples(),
120             getMean(),
121             getStandardError()
122         );
123     }
124 
125     @Override
126     public Mean<N> clone() {
127         return (Mean<N>)super.clone();
128     }
129 
130 }