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