View Javadoc

1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.math.stat.descriptive;
17  
18  import java.io.Serializable;
19  
20  import org.apache.commons.discovery.tools.DiscoverClass;
21  import org.apache.commons.math.util.MathUtils;
22  
23  /**
24   * Abstract factory class for univariate statistical summaries.
25   *
26   * @version $Revision: 348519 $ $Date: 2005-11-23 12:12:18 -0700 (Wed, 23 Nov 2005) $
27   */
28  public abstract class SummaryStatistics implements StatisticalSummary, Serializable {
29  
30      /** Serialization UID */
31      private static final long serialVersionUID = -6400596334135654825L;
32       
33      /**
34       * Create an instance of a <code>SummaryStatistics</code>
35       * 
36       * @param cls the type of <code>SummaryStatistics</code> object to
37       *        create. 
38       * @return a new factory. 
39       * @throws InstantiationException is thrown if the object can not be
40       *            created.
41       * @throws IllegalAccessException is thrown if the type's default
42       *            constructor is not accessible.
43       */
44      public static SummaryStatistics newInstance(Class cls) throws 
45          InstantiationException, IllegalAccessException {
46          return (SummaryStatistics)cls.newInstance();
47      }
48      
49      /**
50       * Create an instance of a <code>SummaryStatistics</code>
51       * 
52       * @return a new SummaryStatistics instance. 
53       */
54      public static SummaryStatistics newInstance() {
55          SummaryStatistics instance = null;
56          try {
57              DiscoverClass dc = new DiscoverClass();
58              instance = (SummaryStatistics) dc.newInstance(
59                  SummaryStatistics.class,
60                  "org.apache.commons.math.stat.descriptive.SummaryStatisticsImpl");
61          } catch(Throwable t) {
62              return new SummaryStatisticsImpl();
63          }
64          return instance;
65      }
66      
67  
68      /**
69       * Return a {@link StatisticalSummaryValues} instance reporting current
70       * statistics.
71       * 
72       * @return Current values of statistics 
73       */
74      public StatisticalSummary getSummary() {
75          return new StatisticalSummaryValues(getMean(), getVariance(), getN(),
76                  getMax(), getMin(), getSum());
77      }
78      
79      /**
80       * Adds the value to the data to be summarized
81       * @param v the value to be added 
82       */
83      public abstract void addValue(double v);
84  
85      /** 
86       * Returns the <a href="http://www.xycoon.com/arithmetic_mean.htm">
87       * arithmetic mean </a> of the available values 
88       * @return The mean or Double.NaN if no values have been added.
89       */
90      public abstract double getMean();
91  
92      /** 
93       * Returns the <a href="http://www.xycoon.com/geometric_mean.htm">
94       * geometric mean </a> of the available values
95       * @return The geometricMean, Double.NaN if no values have been added, 
96       * or if the productof the available values is less than or equal to 0.
97       */
98      public abstract double getGeometricMean();
99  
100     /** 
101      * Returns the variance of the available values.
102      * @return The variance, Double.NaN if no values have been added 
103      * or 0.0 for a single value set.  
104      */
105     public abstract double getVariance();
106 
107     /** 
108      * Returns the standard deviation of the available values.
109      * @return The standard deviation, Double.NaN if no values have been added 
110      * or 0.0 for a single value set. 
111      */
112     public abstract double getStandardDeviation();
113     
114     /** 
115      * Returns the maximum of the available values
116      * @return The max or Double.NaN if no values have been added.
117      */
118     public abstract double getMax();
119 
120     /** 
121     * Returns the minimum of the available values
122     * @return The min or Double.NaN if no values have been added.
123     */
124     public abstract double getMin();
125 
126     /** 
127      * Returns the number of available values
128      * @return The number of available values
129      */
130     public abstract long getN();
131 
132     /**
133      * Returns the sum of the values that have been added to Univariate.
134      * @return The sum or Double.NaN if no values have been added
135      */
136     public abstract double getSum();
137 
138     /**
139      * Returns the sum of the squares of the available values.
140      * @return The sum of the squares or Double.NaN if no 
141      * values have been added.
142      */
143     public abstract double getSumsq();
144 
145     /** 
146      * Resets all statistics
147      */
148     public abstract void clear();
149     
150     /**
151      * Returns true iff <code>object</code> is a <code>SummaryStatistics</code>
152      * instance and all statistics have the same values as this.
153      * @param object the object to test equality against.
154      * @return true if object equals this
155      */
156     public boolean equals(Object object) {
157         if (object == this ) {
158             return true;
159         }
160         if (object instanceof SummaryStatistics == false) {
161             return false;
162         }
163         SummaryStatistics stat = (SummaryStatistics) object;
164         return (MathUtils.equals(stat.getGeometricMean(), 
165                 this.getGeometricMean()) &&
166                 MathUtils.equals(stat.getMax(), this.getMax()) && 
167                 MathUtils.equals(stat.getMean(),this.getMean()) &&
168                 MathUtils.equals(stat.getMin(),this.getMin()) &&
169                 MathUtils.equals(stat.getN(), this.getN()) &&
170                 MathUtils.equals(stat.getSum(), this.getSum()) &&
171                 MathUtils.equals(stat.getSumsq(),this.getSumsq()) &&
172                 MathUtils.equals(stat.getVariance(),this.getVariance()));
173     }
174     
175     /**
176      * Returns hash code based on values of statistics
177      * 
178      * @return hash code
179      */
180     public int hashCode() {
181         int result = 31 + MathUtils.hash(getGeometricMean());
182         result = result * 31 + MathUtils.hash(getGeometricMean());
183         result = result * 31 + MathUtils.hash(getMax());
184         result = result * 31 + MathUtils.hash(getMean());
185         result = result * 31 + MathUtils.hash(getMin());
186         result = result * 31 + MathUtils.hash(getN());
187         result = result * 31 + MathUtils.hash(getSum());
188         result = result * 31 + MathUtils.hash(getSumsq());
189         result = result * 31 + MathUtils.hash(getVariance());
190         return result;
191     }
192 
193 }