DoubleMomentStatistics.java
001 /*
002  * Java Genetic Algorithm Library (jenetics-3.8.0).
003  * Copyright (c) 2007-2017 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.Math.max;
023 import static java.lang.Math.min;
024 import static java.util.Objects.requireNonNull;
025 
026 import java.util.function.DoubleConsumer;
027 import java.util.function.ToDoubleFunction;
028 import java.util.stream.Collector;
029 
030 import org.jenetics.internal.math.DoubleAdder;
031 
032 /**
033  * A state object for collecting statistics such as count, min, max, sum, mean,
034  * variance, skewness and kurtosis. The design of this class is similar to the
035  {@link java.util.DoubleSummaryStatistics} class.
036  <p>
037  * This class is designed to work with (though does not require) streams. For
038  * example, you can compute moments-statistics on a stream of doubles with:
039  <pre>{@code
040  * final DoubleStream stream = ...
041  * final DoubleMomentStatistics statistics = stream.collect(
042  *         DoubleMomentStatistics::new,
043  *         DoubleMomentStatistics::accept,
044  *         DoubleMomentStatistics::combine
045  *     );
046  * }</pre>
047  *
048  * For a non double stream, you can use a collector:
049  <pre>{@code
050  * final Stream<SomeObject> stream = ...
051  * final DoubleMomentStatistics statistics = stream
052  *     .collect(toDoubleMomentStatistics(v -> v.doubleValue()));
053  * }</pre>
054  *
055  <p>
056  <b>Implementation note:</b>
057  <i>This implementation is not thread safe. However, it is safe to use
058  {@link #toDoubleMomentStatistics(ToDoubleFunction)}  on a parallel stream,
059  * because the parallel implementation of
060  {@link java.util.stream.Stream#collect Stream.collect()}
061  * provides the necessary partitioning, isolation, and merging of results for
062  * safe and efficient parallel execution.</i>
063  *
064  @see java.util.DoubleSummaryStatistics
065  @see org.jenetics.stat.DoubleMoments
066  @see <a href="http://people.xiph.org/~tterribe/notes/homs.html">
067  *      Computing Higher-Order Moments Online</a>
068  *
069  @author <a href="mailto:franz.wilhelmstoetter@gmx.at">Franz Wilhelmstötter</a>
070  @since 3.0
071  @version 3.7
072  */
073 public class DoubleMomentStatistics
074     extends MomentStatistics
075     implements DoubleConsumer
076 {
077 
078     private double _min = Double.POSITIVE_INFINITY;
079     private double _max = Double.NEGATIVE_INFINITY;
080 
081     private final DoubleAdder _sum = new DoubleAdder();
082 
083     /**
084      * Create an empty moments object.
085      */
086     public DoubleMomentStatistics() {
087     }
088 
089     /**
090      * Records a new value into the moments information
091      *
092      @param value the input {@code value}
093      */
094     @Override
095     public void accept(final double value) {
096         super.accept(value);
097         _min = min(_min, value);
098         _max = max(_max, value);
099         _sum.add(value);
100     }
101 
102     /**
103      * Combine two {@code DoubleMoments} statistic objects.
104      *
105      @param other the other {@code DoubleMoments} statistics to combine with
106      *        {@code this} one.
107      @return {@code this} statistics object
108      @throws java.lang.NullPointerException if the other statistical summary
109      *         is {@code null}.
110      */
111     public DoubleMomentStatistics combine(final DoubleMomentStatistics other) {
112         super.combine(other);
113         _min = min(_min, other._min);
114         _max = max(_max, other._max);
115         _sum.add(other._sum);
116 
117         return this;
118     }
119 
120     /**
121      * Return the minimum value recorded, or {@code Double.POSITIVE_INFINITY} if
122      * no values have been recorded.
123      *
124      @return the minimum value, or {@code Double.POSITIVE_INFINITY} if none
125      */
126     public double getMin() {
127         return _min;
128     }
129 
130     /**
131      * Return the maximum value recorded, or {@code Double.NEGATIVE_INFINITY} if
132      * no values have been recorded.
133      *
134      @return the maximum value, or {@code Double.NEGATIVE_INFINITY} if none
135      */
136     public double getMax() {
137         return _max;
138     }
139 
140     /**
141      * Return the sum of values recorded, or zero if no values have been
142      * recorded.
143      *
144      @return the sum of values, or zero if none
145      */
146     public double getSum() {
147         return _sum.doubleValue();
148     }
149 
150     /**
151      * Compares the state of two {@code DoubleMomentStatistics} objects. This is
152      * a replacement for the {@link #equals(Object)} which is not advisable to
153      * implement for this mutable object. If two object have the same state, it
154      * has still the same state when updated with the same value.
155      <pre>{@code
156      * final DoubleMomentStatistics ds1 = ...;
157      * final DoubleMomentStatistics ds2 = ...;
158      *
159      * if (ds1.sameState(ds2)) {
160      *     final double value = random.nextDouble();
161      *     ds1.accept(value);
162      *     ds2.accept(value);
163      *
164      *     assert ds1.sameState(ds2);
165      *     assert ds2.sameState(ds1);
166      *     assert ds1.sameState(ds1);
167      * }
168      * }</pre>
169      *
170      @since 3.7
171      *
172      @param other the other object for the test
173      @return {@code true} the {@code this} and the {@code other} objects have
174      *         the same state, {@code false} otherwise
175      */
176     public boolean sameState(final DoubleMomentStatistics other) {
177         return Double.compare(_min, other._min== &&
178             Double.compare(_max, other._max== &&
179             _sum.sameState(other._sum&&
180             super.sameState(other);
181     }
182 
183     @Override
184     public String toString() {
185         return String.format(
186             "Summary[N=%d, ∧=%s, ∨=%s, Σ=%s, μ=%s, s²=%s, S=%s, K=%s]",
187             getCount(), _min, _max, _sum.doubleValue(),
188             getMean(), getVariance(), getSkewness(), getKurtosis()
189         );
190     }
191 
192     /**
193      * Return a {@code Collector} which applies an double-producing mapping
194      * function to each input element, and returns moments-statistics for the
195      * resulting values.
196      *
197      <pre>{@code
198      * final Stream<SomeObject> stream = ...
199      * final DoubleMomentStatistics statistics = stream
200      *     .collect(toDoubleMomentStatistics(v -> v.doubleValue()));
201      * }</pre>
202      *
203      @param mapper a mapping function to apply to each element
204      @param <T> the type of the input elements
205      @return a {@code Collector} implementing the moments-statistics reduction
206      @throws java.lang.NullPointerException if the given {@code mapper} is
207      *         {@code null}
208      */
209     public static <T> Collector<T, ?, DoubleMomentStatistics>
210     toDoubleMomentStatistics(final ToDoubleFunction<? super T> mapper) {
211         requireNonNull(mapper);
212         return Collector.of(
213             DoubleMomentStatistics::new,
214             (r, t-> r.accept(mapper.applyAsDouble(t)),
215             DoubleMomentStatistics::combine
216         );
217     }
218 
219 }