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 <= 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 }