Mean.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-1.6.0).
003  * Copyright (c) 2007-2014 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.internal.util.object.eq;
024 
025 import org.jenetics.internal.util.HashBuilder;
026 
027 import org.jenetics.util.MappedAccumulator;
028 
029 
030 /**
031  <p>Calculate  the Arithmetic mean from a finite sample of <i>N</i>
032  * observations.</p>
033  <p><img src="doc-files/arithmetic-mean.gif"
034  *         alt="\bar{x}=\frac{1}{N}\sum_{i=1}^{N}x_i"
035  *    />
036  </p>
037  *
038  <p/>
039  <strong>Note that this implementation is not synchronized.</strong> If
040  * multiple threads access this object concurrently, and at least one of the
041  * threads modifies it, it must be synchronized externally.
042  *
043  @see <a href="http://mathworld.wolfram.com/ArithmeticMean.html">Wolfram MathWorld: Artithmetic Mean</a>
044  @see <a href="http://en.wikipedia.org/wiki/Arithmetic_mean">Wikipedia: Arithmetic Mean</a>
045  *
046  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
047  @since 1.0
048  @version 1.0 &mdash; <em>$Date: 2014-03-01 $</em>
049  */
050 public class Mean<N extends Number> extends MappedAccumulator<N> {
051 
052     protected double _mean = Double.NaN;
053 
054     public Mean() {
055     }
056 
057     /**
058      * Return the mean value of the accumulated values.
059      *
060      @return the mean value of the accumulated values, or {@link java.lang.Double#NaN}
061      *          if {@code getSamples() == 0}.
062      */
063     public double getMean() {
064         return _mean;
065     }
066 
067     /**
068      * Return the
069      * <a href="https://secure.wikimedia.org/wikipedia/en/wiki/Standard_error_%28statistics%29">
070      * Standard error
071      </a> of the calculated mean.
072      *
073      @return the standard error of the calculated mean.
074      */
075     public double getStandardError() {
076         double sem = Double.NaN;
077 
078         if (_samples > 0) {
079             sem = _mean/Math.sqrt(_samples);
080         }
081 
082         return sem;
083     }
084 
085     /**
086      @throws NullPointerException if the given {@code value} is {@code null}.
087      */
088     @Override
089     public void accumulate(final N value) {
090         if (_samples == 0) {
091             _mean = 0;
092         }
093 
094         _mean += (value.doubleValue() - _mean)/(++_samples);
095     }
096 
097     @Override
098     public int hashCode() {
099         return HashBuilder.of(getClass()).and(super.hashCode()).and(_mean).value();
100     }
101 
102     @Override
103     public boolean equals(final Object obj) {
104         if (obj == this) {
105             return true;
106         }
107         if (obj == null || getClass() != obj.getClass()) {
108             return false;
109         }
110 
111         final Mean<?> mean = (Mean<?>)obj;
112         return eq(_mean, mean._mean&& super.equals(mean);
113     }
114 
115     @Override
116     public String toString() {
117         return format(
118             "%s[samples=%d, mean=%f, stderr=%f]",
119             getClass().getSimpleName(),
120             getSamples(),
121             getMean(),
122             getStandardError()
123         );
124     }
125 
126     @Override
127     public Mean<N> clone() {
128         return (Mean<N>)super.clone();
129     }
130 
131 }