001 /*
002 * Java Genetic Algorithm Library (jenetics-5.2.0).
003 * Copyright (c) 2007-2020 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.lang.Double.NaN;
023 import static java.util.Objects.requireNonNull;
024 import static io.jenetics.internal.util.Hashes.hash;
025
026 import java.io.Serializable;
027 import java.util.LongSummaryStatistics;
028 import java.util.function.ToLongFunction;
029 import java.util.stream.Collector;
030
031 /**
032 * <i>Value</i> objects which contains statistical summary information.
033 *
034 * @see java.util.LongSummaryStatistics
035 *
036 * @implNote
037 * This class is immutable and thread-safe.
038 *
039 * @author <a href="mailto:franz.wilhelmstoetter@gmail.com">Franz Wilhelmstötter</a>
040 * @since 3.0
041 * @version 5.2
042 */
043 public final /*record*/ class LongSummary implements Serializable {
044
045 private static final long serialVersionUID = 1L;
046
047 private final long _count;
048 private final long _min;
049 private final long _max;
050 private final long _sum;
051 private final double _mean;
052
053 /**
054 * Create an immutable object which contains statistical summary values.
055 *
056 * @param count the count of values recorded
057 * @param min the minimum value
058 * @param max the maximum value
059 * @param sum the sum of the recorded values
060 * @param mean the arithmetic mean of values
061 */
062 private LongSummary(
063 final long count,
064 final long min,
065 final long max,
066 final long sum,
067 final double mean
068 ) {
069 _count = count;
070 _min = min;
071 _max = max;
072 _sum = sum;
073 _mean = mean;
074 }
075
076 /**
077 * Returns the count of values recorded.
078 *
079 * @return the count of recorded values
080 */
081 public long count() {
082 return _count;
083 }
084
085 /**
086 * Returns the count of values recorded.
087 *
088 * @return the count of recorded values
089 * @deprecated Use {@link #count()} instead
090 */
091 @Deprecated
092 public long getCount() {
093 return _count;
094 }
095
096 /**
097 * Return the minimum value recorded, or {@code Long.MAX_VALUE} if no
098 * values have been recorded.
099 *
100 * @return the minimum value, or {@code Long.MAX_VALUE} if none
101 */
102 public long min() {
103 return _min;
104 }
105
106 /**
107 * Return the minimum value recorded, or {@code Long.MAX_VALUE} if no
108 * values have been recorded.
109 *
110 * @return the minimum value, or {@code Long.MAX_VALUE} if none
111 * @deprecated Use {@link #min()} instead
112 */
113 @Deprecated
114 public long getMin() {
115 return _min;
116 }
117
118 /**
119 * Return the maximum value recorded, or {@code Long.MIN_VALUE} if no
120 * values have been recorded.
121 *
122 * @return the maximum value, or {@code Long.MIN_VALUE} if none
123 */
124 public long max() {
125 return _max;
126 }
127
128 /**
129 * Return the maximum value recorded, or {@code Long.MIN_VALUE} if no
130 * values have been recorded.
131 *
132 * @return the maximum value, or {@code Long.MIN_VALUE} if none
133 * @deprecated Use {@link #max()} instead
134 */
135 @Deprecated
136 public long 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 long sum() {
147 return _sum;
148 }
149
150 /**
151 * Return the sum of values recorded, or zero if no values have been
152 * recorded.
153 *
154 * @return the sum of values, or zero if none
155 * @deprecated Use {@link #sum()} instead
156 */
157 @Deprecated
158 public long getSum() {
159 return _sum;
160 }
161
162 /**
163 * Return the arithmetic mean of values recorded, or zero if no values have
164 * been recorded.
165 *
166 * @return the arithmetic mean of values, or zero if none
167 */
168 public double getMean() {
169 return _mean;
170 }
171
172 @Override
173 public int hashCode() {
174 return
175 hash(_count,
176 hash(_sum,
177 hash(_min,
178 hash(_max,
179 hash(_mean)))));
180 }
181
182 @Override
183 public boolean equals(final Object obj) {
184 return obj == this ||
185 obj instanceof LongSummary &&
186 _count == ((LongSummary)obj)._count &&
187 _sum == ((LongSummary)obj)._sum &&
188 _min == ((LongSummary)obj)._min &&
189 _max == ((LongSummary)obj)._max &&
190 Double.compare(_mean, ((LongSummary)obj)._mean) == 0;
191 }
192
193 @Override
194 public String toString() {
195 return String.format(
196 "LongSummary[N=%d, ∧=%s, ∨=%s, Σ=%s, μ=%s]",
197 count(), min(), max(), sum(), getMean()
198 );
199 }
200
201 /**
202 * Create an immutable object which contains statistical summary values.
203 *
204 * @param count the count of values recorded
205 * @param min the minimum value
206 * @param max the maximum value
207 * @param sum the sum of the recorded values
208 * @param mean the arithmetic mean of values
209 * @return an immutable object which contains statistical values
210 */
211 public static LongSummary of(
212 final long count,
213 final long min,
214 final long max,
215 final long sum,
216 final double mean
217 ) {
218 return new LongSummary(
219 count,
220 min,
221 max,
222 sum,
223 mean
224 );
225 }
226
227 /**
228 * Return a new value object of the statistical summary, currently
229 * represented by the {@code statistics} object.
230 *
231 * @param statistics the creating (mutable) statistics class
232 * @return the statistical moments
233 */
234 public static LongSummary of(final LongSummaryStatistics statistics) {
235 return new LongSummary(
236 statistics.getCount(),
237 statistics.getMin(),
238 statistics.getMax(),
239 statistics.getSum(),
240 statistics.getAverage()
241 );
242 }
243
244 /**
245 * Return a {@code Collector} which applies an long-producing mapping
246 * function to each input element, and returns summary-statistics for the
247 * resulting values.
248 *
249 * <pre>{@code
250 * final Stream<SomeObject> stream = ...
251 * final LongSummary summary = stream
252 * .collect(toLongSummary(v -> v.longValue()));
253 * }</pre>
254 *
255 * @param mapper a mapping function to apply to each element
256 * @param <T> the type of the input elements
257 * @return a {@code Collector} implementing the summary-statistics reduction
258 * @throws java.lang.NullPointerException if the given {@code mapper} is
259 * {@code null}
260 */
261 public static <T> Collector<T, ?, LongSummary>
262 toLongSummary(final ToLongFunction<? super T> mapper) {
263 requireNonNull(mapper);
264 return Collector.of(
265 LongSummaryStatistics::new,
266 (a, b) -> a.accept(mapper.applyAsLong(b)),
267 (a, b) -> {a.combine(b); return a;},
268 LongSummary::of
269 );
270 }
271
272
273 /* *************************************************************************
274 * Some static helper methods.
275 **************************************************************************/
276
277 /**
278 * Return the minimum value of the given double array.
279 *
280 * @since 4.0
281 *
282 * @param values the array.
283 * @return the minimum value or {@link Long#MAX_VALUE} if the given array is
284 * empty.
285 * @throws NullPointerException if the given array is {@code null}.
286 */
287 public static long min(final long[] values) {
288 long min = Long.MAX_VALUE;
289 if (values.length > 0) {
290 min = values[0];
291 for (long value : values) {
292 if (value < min) {
293 min = value;
294 }
295 }
296 }
297
298 return min;
299 }
300
301 /**
302 * Return the maximum value of the given double array.
303 *
304 * @since 4.0
305 *
306 * @param values the array.
307 * @return the maximum value or {@link Long#MIN_VALUE} if the given array is
308 * empty.
309 * @throws NullPointerException if the given array is {@code null}.
310 */
311 public static long max(final long[] values) {
312 long max = Long.MIN_VALUE;
313 if (values.length > 0) {
314 max = values[0];
315 for (long value : values) {
316 if (value > max) {
317 max = value;
318 }
319 }
320 }
321
322 return max;
323 }
324
325 /**
326 * Return the sum of the given double array.
327 *
328 * @since 4.0
329 *
330 * @param values the values to sum up.
331 * @return the sum of the given {@code values}.
332 * @throws NullPointerException if the given array is {@code null}.
333 */
334 public static long sum(final long[] values) {
335 long sum = 0;
336 for (int i = values.length; --i >= 0;) {
337 sum += values[i];
338 }
339 return sum;
340 }
341
342 /**
343 * Returns a double describing the arithmetic mean of the values, or
344 * {@link Double#NaN} if the {@code values} array is empty.
345 *
346 * @since 4.0
347 *
348 * @param values the values to calculate the mean of
349 * @return the arithmetic mean of the given {@code values} or
350 * {@link Double#NaN} if the {@code values} array is empty
351 * @throws NullPointerException if the given array is {@code null}.
352 */
353 public static double mean(final long[] values) {
354 return values.length > 0 ? (double)sum(values)/values.length : NaN;
355 }
356
357 }
|