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.moment;
23  
24  import java.io.Serializable;
25  
26  import org.hipparchus.exception.NullArgumentException;
27  
28  
29  /**
30   * Computes a statistic related to the Third Central Moment.  Specifically,
31   * what is computed is the sum of cubed deviations from the sample mean.
32   * <p>
33   * The following recursive updating formula is used:
34   * <p>
35   * Let <ul>
36   * <li> dev = (current obs - previous mean) </li>
37   * <li> m2 = previous value of {@link SecondMoment} </li>
38   * <li> n = number of observations (including current obs) </li>
39   * </ul>
40   * Then
41   * <p>
42   * new value = old value - 3 * (dev/n) * m2 + (n-1) * (n -2) * (dev^3/n^2)
43   * <p>
44   * Returns <code>Double.NaN</code> if no data values have been added and
45   * returns <code>0</code> if there is just one value in the data set.
46   * Note that Double.NaN may also be returned if the input includes NaN
47   * and / or infinite values.
48   * <p>
49   * <strong>Note that this implementation is not synchronized.</strong> If
50   * multiple threads access an instance of this class concurrently, and at least
51   * one of the threads invokes the <code>increment()</code> or
52   * <code>clear()</code> method, it must be synchronized externally.
53   */
54  class ThirdMoment extends SecondMoment implements Serializable {
55  
56      /** Serializable version identifier */
57      private static final long serialVersionUID = 20150412L;
58  
59      /** third moment of values that have been added */
60      protected double m3;
61  
62      /**
63       * Square of deviation of most recently added value from previous first
64       * moment, normalized by previous sample size.  Retained to prevent
65       * repeated computation in higher order moments.  nDevSq = nDev * nDev.
66       */
67      protected double nDevSq;
68  
69      /**
70       * Create a FourthMoment instance.
71       */
72      ThirdMoment() {
73          super();
74          m3 = Double.NaN;
75          nDevSq = Double.NaN;
76      }
77  
78      /**
79       * Copy constructor, creates a new {@code ThirdMoment} identical
80       * to the {@code original}.
81       *
82       * @param original the {@code ThirdMoment} instance to copy
83       * @throws NullArgumentException if original is null
84       */
85      ThirdMoment(ThirdMoment original) throws NullArgumentException {
86          super(original);
87          this.m3     = original.m3;
88          this.nDevSq = original.nDevSq;
89      }
90  
91      /** {@inheritDoc} */
92      @Override
93      public void increment(final double d) {
94          if (n < 1) {
95              m3 = m2 = m1 = 0.0;
96          }
97  
98          double prevM2 = m2;
99          super.increment(d);
100         nDevSq = nDev * nDev;
101         double n0 = n;
102         m3 = m3 - 3.0 * nDev * prevM2 + (n0 - 1) * (n0 - 2) * nDevSq * dev;
103     }
104 
105     /** {@inheritDoc} */
106     @Override
107     public double getResult() {
108         return m3;
109     }
110 
111     /** {@inheritDoc} */
112     @Override
113     public void clear() {
114         super.clear();
115         m3 = Double.NaN;
116         nDevSq = Double.NaN;
117     }
118 
119     /**
120      * Throws {@link UnsupportedOperationException}.
121      */
122     @Override
123     public void aggregate(SecondMoment other) {
124         throw new UnsupportedOperationException();
125     }
126 
127     /** {@inheritDoc} */
128     @Override
129     public ThirdMoment copy() {
130         return new ThirdMoment(this);
131     }
132 
133 }