Home | History | Annotate | Download | only in moment 
      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  *      http://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 package org.apache.commons.math.stat.descriptive.moment;
     18 
     19 import java.io.Serializable;
     20 
     21 /**
     22  * Computes a statistic related to the Second Central Moment.  Specifically,
     23  * what is computed is the sum of squared deviations from the sample mean.
     24  * <p>
     25  * The following recursive updating formula is used:</p>
     26  * <p>
     27  * Let <ul>
     28  * <li> dev = (current obs - previous mean) </li>
     29  * <li> n = number of observations (including current obs) </li>
     30  * </ul>
     31  * Then</p>
     32  * <p>
     33  * new value = old value + dev^2 * (n -1) / n.</p>
     34  * <p>
     35  * Returns <code>Double.NaN</code> if no data values have been added and
     36  * returns <code>0</code> if there is just one value in the data set.</p>
     37  * <p>
     38  * <strong>Note that this implementation is not synchronized.</strong> If
     39  * multiple threads access an instance of this class concurrently, and at least
     40  * one of the threads invokes the <code>increment()</code> or
     41  * <code>clear()</code> method, it must be synchronized externally.</p>
     42  *
     43  * @version $Revision: 811685 $ $Date: 2009-09-05 19:36:48 +0200 (sam. 05 sept. 2009) $
     44  */
     45 public class SecondMoment extends FirstMoment implements Serializable {
     46 
     47     /** Serializable version identifier */
     48     private static final long serialVersionUID = 3942403127395076445L;
     49 
     50     /** second moment of values that have been added */
     51     protected double m2;
     52 
     53     /**
     54      * Create a SecondMoment instance
     55      */
     56     public SecondMoment() {
     57         super();
     58         m2 = Double.NaN;
     59     }
     60 
     61     /**
     62      * Copy constructor, creates a new {@code SecondMoment} identical
     63      * to the {@code original}
     64      *
     65      * @param original the {@code SecondMoment} instance to copy
     66      */
     67     public SecondMoment(SecondMoment original) {
     68         super(original);
     69         this.m2 = original.m2;
     70     }
     71 
     72     /**
     73      * {@inheritDoc}
     74      */
     75     @Override
     76     public void increment(final double d) {
     77         if (n < 1) {
     78             m1 = m2 = 0.0;
     79         }
     80         super.increment(d);
     81         m2 += ((double) n - 1) * dev * nDev;
     82     }
     83 
     84     /**
     85      * {@inheritDoc}
     86      */
     87     @Override
     88     public void clear() {
     89         super.clear();
     90         m2 = Double.NaN;
     91     }
     92 
     93     /**
     94      * {@inheritDoc}
     95      */
     96     @Override
     97     public double getResult() {
     98         return m2;
     99     }
    100 
    101     /**
    102      * {@inheritDoc}
    103      */
    104     @Override
    105     public SecondMoment copy() {
    106         SecondMoment result = new SecondMoment();
    107         copy(this, result);
    108         return result;
    109     }
    110 
    111     /**
    112      * Copies source to dest.
    113      * <p>Neither source nor dest can be null.</p>
    114      *
    115      * @param source SecondMoment to copy
    116      * @param dest SecondMoment to copy to
    117      * @throws NullPointerException if either source or dest is null
    118      */
    119     public static void copy(SecondMoment source, SecondMoment dest) {
    120         FirstMoment.copy(source, dest);
    121         dest.m2 = source.m2;
    122     }
    123 
    124 }
    125