1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.stat.descriptive;
23
24 import java.util.Arrays;
25
26 import org.hipparchus.util.MathUtils;
27
28 /**
29 * Reporting interface for basic univariate statistics.
30 */
31 public interface StatisticalSummary {
32
33 /**
34 * Computes aggregated statistical summaries.
35 * <p>
36 * This method can be used to combine statistics computed over partitions or
37 * subsamples - i.e., the returned StatisticalSummary should contain
38 * the same values that would have been obtained by computing a single
39 * StatisticalSummary over the combined dataset.
40 *
41 * @param statistics StatisticalSummary instances to aggregate
42 * @return summary statistics for the combined dataset
43 * @throws org.hipparchus.exception.NullArgumentException if the input is null
44 */
45 static StatisticalSummary aggregate(StatisticalSummary... statistics) {
46 MathUtils.checkNotNull(statistics);
47 return aggregate(Arrays.asList(statistics));
48 }
49
50 /**
51 * Computes aggregated statistical summaries.
52 * <p>
53 * This method can be used to combine statistics computed over partitions or
54 * subsamples - i.e., the returned StatisticalSummary should contain
55 * the same values that would have been obtained by computing a single
56 * StatisticalSummary over the combined dataset.
57 *
58 * @param statistics iterable of StatisticalSummary instances to aggregate
59 * @return summary statistics for the combined dataset
60 * @throws org.hipparchus.exception.NullArgumentException if the input is null
61 */
62 static StatisticalSummary aggregate(Iterable<? extends StatisticalSummary> statistics) {
63 MathUtils.checkNotNull(statistics);
64
65 long n = 0;
66 double min = Double.NaN;
67 double max = Double.NaN;
68 double sum = Double.NaN;
69 double mean = Double.NaN;
70 double m2 = Double.NaN;
71
72 for (StatisticalSummary current : statistics) {
73 if (current.getN() == 0) {
74 continue;
75 }
76
77 if (n == 0) {
78 n = current.getN();
79 min = current.getMin();
80 sum = current.getSum();
81 max = current.getMax();
82 m2 = current.getVariance() * (n - 1);
83 mean = current.getMean();
84 } else {
85 if (current.getMin() < min) {
86 min = current.getMin();
87 }
88 if (current.getMax() > max) {
89 max = current.getMax();
90 }
91
92 sum += current.getSum();
93 final double oldN = n;
94 final double curN = current.getN();
95 n += curN;
96 final double meanDiff = current.getMean() - mean;
97 mean = sum / n;
98 final double curM2 = current.getVariance() * (curN - 1d);
99 m2 = m2 + curM2 + meanDiff * meanDiff * oldN * curN / n;
100 }
101 }
102
103 final double variance = n == 0 ? Double.NaN :
104 n == 1 ? 0d :
105 m2 / (n - 1);
106
107 return new StatisticalSummaryValues(mean, variance, n, max, min, sum);
108 }
109
110 /**
111 * Returns the <a href="http://www.xycoon.com/arithmetic_mean.htm">
112 * arithmetic mean </a> of the available values
113 * @return The mean or Double.NaN if no values have been added.
114 */
115 double getMean();
116
117 /**
118 * Returns the variance of the available values.
119 * @return The variance, Double.NaN if no values have been added
120 * or 0.0 for a single value set.
121 */
122 double getVariance();
123
124 /**
125 * Returns the standard deviation of the available values.
126 * @return The standard deviation, Double.NaN if no values have been added
127 * or 0.0 for a single value set.
128 */
129 double getStandardDeviation();
130
131 /**
132 * Returns the maximum of the available values
133 * @return The max or Double.NaN if no values have been added.
134 */
135 double getMax();
136
137 /**
138 * Returns the minimum of the available values
139 * @return The min or Double.NaN if no values have been added.
140 */
141 double getMin();
142
143 /**
144 * Returns the number of available values
145 * @return The number of available values
146 */
147 long getN();
148
149 /**
150 * Returns the sum of the values that have been added to Univariate.
151 * @return The sum or Double.NaN if no values have been added
152 */
153 double getSum();
154
155 }