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    *      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 org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
20  import org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic;
21  import org.apache.commons.math.stat.descriptive.summary.SumOfLogs;
22  
23  /**
24   * Returns the <a href="http://www.xycoon.com/geometric_mean.htm">
25   * geometric mean </a> of the available values.
26   * <p>
27   * Uses a {@link SumOfLogs} instance to compute sum of logs and returns
28   * <code> exp( 1/n  (sum of logs) ).</code>  Therefore, </p>
29   * <ul>
30   * <li>If any of values are < 0, the result is <code>NaN.</code></li>
31   * <li>If all values are non-negative and less than 
32   * <code>Double.POSITIVE_INFINITY</code>,  but at least one value is 0, the 
33   * result is <code>0.</code></li>
34   * <li>If both <code>Double.POSITIVE_INFINITY</code> and 
35   * <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
36   * <code>NaN.</code></li>
37   * </ul> </p>
38   * <p>
39   * <strong>Note that this implementation is not synchronized.</strong> If 
40   * multiple threads access an instance of this class concurrently, and at least
41   * one of the threads invokes the <code>increment()</code> or 
42   * <code>clear()</code> method, it must be synchronized externally.</p>
43   * 
44   *
45   * @version $Revision: 628352 $ $Date: 2008-02-16 09:39:03 -0700 (Sat, 16 Feb 2008) $
46   */
47  public class GeometricMean extends AbstractStorelessUnivariateStatistic {
48  
49      /** Serializable version identifier */
50      private static final long serialVersionUID = -8178734905303459453L;  
51      
52      /** Wrapped SumOfLogs instance */
53      private StorelessUnivariateStatistic sumOfLogs;
54  
55      /**
56       * Create a GeometricMean instance
57       */
58      public GeometricMean() {
59          sumOfLogs = new SumOfLogs();
60      }
61      
62      /**
63       * Create a GeometricMean instance using the given SumOfLogs instance
64       */
65      public GeometricMean(SumOfLogs sumOfLogs) {
66          this.sumOfLogs = sumOfLogs;
67      }
68      
69      /**
70       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#increment(double)
71       */
72      public void increment(final double d) {
73          sumOfLogs.increment(d);
74      }
75  
76      /**
77       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getResult()
78       */
79      public double getResult() {
80          if (sumOfLogs.getN() > 0) {
81              return Math.exp(sumOfLogs.getResult() / (double) sumOfLogs.getN());
82          } else {
83              return Double.NaN;
84          }
85      }
86  
87      /**
88       * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#clear()
89       */
90      public void clear() {
91          sumOfLogs.clear();
92      }
93  
94      /**
95       * Returns the geometric mean of the entries in the specified portion
96       * of the input array.
97       * <p>
98       * See {@link GeometricMean} for details on the computing algorithm.</p>
99       * <p>
100      * Throws <code>IllegalArgumentException</code> if the array is null.</p>
101      * 
102      * @param values input array containing the values
103      * @param begin first array element to include
104      * @param length the number of elements to include
105      * @return the geometric mean or Double.NaN if length = 0 or
106      * any of the values are &lt;= 0.
107      * @throws IllegalArgumentException if the input array is null or the array
108      * index parameters are not valid
109      */
110     public double evaluate(
111         final double[] values, final int begin, final int length) {
112         return Math.exp(
113             sumOfLogs.evaluate(values, begin, length) / (double) length);
114     }
115     
116     /**
117      * @see org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic#getN()
118      */
119     public long getN() {
120         return sumOfLogs.getN();
121     }
122     
123     /**
124      * <p>Sets the implementation for the sum of logs.</p>
125      * <p>This method must be activated before any data has been added - i.e.,
126      * before {@link #increment(double) increment} has been used to add data; 
127      * otherwise an IllegalStateException will be thrown.</p>
128      * 
129      * @param sumLogImpl the StorelessUnivariateStatistic instance to use
130      * for computing the log sum
131      * @throws IllegalStateException if data has already been added 
132      *  (i.e if n > 0)
133      */
134     public void setSumLogImpl(
135             StorelessUnivariateStatistic sumLogImpl) {
136         checkEmpty();
137         this.sumOfLogs = sumLogImpl;
138     }
139     
140     /**
141      * Returns the currently configured sum of logs implementation
142      * 
143      * @return the StorelessUnivariateStatistic implementing the log sum
144      */
145     public StorelessUnivariateStatistic getSumLogImpl() {
146         return sumOfLogs;
147     }
148     
149     /**
150      * Throws IllegalStateException if n > 0.
151      */
152     private void checkEmpty() {
153         if (getN() > 0) {
154             throw new IllegalStateException(
155                 "Implementation must be configured before values are added.");
156         }
157     }
158 
159 }