View Javadoc
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.function.DoubleConsumer;
25  
26  import org.hipparchus.exception.LocalizedCoreFormats;
27  import org.hipparchus.exception.MathIllegalArgumentException;
28  import org.hipparchus.util.MathArrays;
29  import org.hipparchus.util.MathUtils;
30  
31  /**
32   * Extends the definition of {@link UnivariateStatistic} with
33   * {@link #increment} and {@link #incrementAll(double[])} methods for adding
34   * values and updating internal state.
35   * <p>
36   * This interface is designed to be used for calculating statistics that can be
37   * computed in one pass through the data without storing the full array of
38   * sample values.
39   * <p>
40   * Note: unless otherwise stated, the {@link #evaluate(double[])} and
41   * {@link #evaluate(double[], int, int)} methods do <b>NOT</b> alter the internal
42   * state of the respective statistic.
43   */
44  public interface StorelessUnivariateStatistic
45      extends UnivariateStatistic, DoubleConsumer {
46  
47      /**
48       * {@inheritDoc}
49       * <p>
50       * The default implementation creates a copy of this {@link StorelessUnivariateStatistic}
51       * instance, calls {@link #clear} on it, then calls {@link #incrementAll} with the specified
52       * portion of the input array, and then uses {@link #getResult} to compute the return value.
53       * <p>
54       * Note that this implementation does not change the internal state of the statistic.
55       * <p>
56       * Implementations may override this method with a more efficient and possibly more
57       * accurate implementation that works directly with the input array.
58       *
59       * @param values the input array
60       * @param begin the index of the first element to include
61       * @param length the number of elements to include
62       * @return the value of the statistic applied to the included array entries
63       * @throws MathIllegalArgumentException if the array is null or the indices are not valid
64       * @see UnivariateStatistic#evaluate(double[], int, int)
65       */
66      @Override
67      default double evaluate(final double[] values, final int begin, final int length)
68          throws MathIllegalArgumentException {
69  
70          if (MathArrays.verifyValues(values, begin, length)) {
71              StorelessUnivariateStatistic stat = copy();
72              stat.clear();
73              stat.incrementAll(values, begin, length);
74              return stat.getResult();
75          }
76          return Double.NaN;
77      }
78  
79      /**
80       * Updates the internal state of the statistic to reflect the addition of the new value.
81       * @param d  the new value.
82       */
83      void increment(double d);
84  
85      /** {@inheritDoc} */
86      @Override
87      default void accept(double value) {
88          increment(value);
89      }
90  
91      /**
92       * Updates the internal state of the statistic to reflect addition of
93       * all values in the values array. Does not clear the statistic first --
94       * i.e., the values are added <strong>incrementally</strong> to the dataset.
95       * <p>
96       * The default implementation delegates to
97       * <code>incrementAll(double[], int, int)</code> in the natural way.
98       *
99       * @param values  array holding the new values to add
100      * @throws MathIllegalArgumentException if the array is null
101      */
102     default void incrementAll(double[] values) throws MathIllegalArgumentException {
103         MathUtils.checkNotNull(values, LocalizedCoreFormats.INPUT_ARRAY);
104         incrementAll(values, 0, values.length);
105     }
106 
107 
108     /**
109      * Updates the internal state of the statistic to reflect addition of
110      * the values in the designated portion of the values array.  Does not
111      * clear the statistic first -- i.e., the values are added
112      * <strong>incrementally</strong> to the dataset.
113      * <p>
114      * The default implementation just calls {@link #increment} in a loop over
115      * the specified portion of the input array.
116      *
117      * @param values  array holding the new values to add
118      * @param start  the array index of the first value to add
119      * @param length  the number of elements to add
120      * @throws MathIllegalArgumentException if the array is null or the index
121      */
122     default void incrementAll(double[] values, int start, int length)
123         throws MathIllegalArgumentException {
124 
125         if (MathArrays.verifyValues(values, start, length)) {
126             int k = start + length;
127             for (int i = start; i < k; i++) {
128                 increment(values[i]);
129             }
130         }
131     }
132 
133 
134     /**
135      * Returns the current value of the Statistic.
136      * @return value of the statistic, <code>Double.NaN</code> if it
137      * has been cleared or just instantiated.
138      */
139     double getResult();
140 
141     /**
142      * Returns the number of values that have been added.
143      * @return the number of values.
144      */
145     long getN();
146 
147     /**
148      * Clears the internal state of the Statistic
149      */
150     void clear();
151 
152     /**
153      * Returns a copy of the statistic with the same internal state.
154      *
155      * @return a copy of the statistic
156      */
157     @Override
158     StorelessUnivariateStatistic copy();
159 
160 }