001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math.stat.descriptive.moment;
018
019 import java.io.Serializable;
020
021 import org.apache.commons.math.MathRuntimeException;
022 import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
023 import org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic;
024 import org.apache.commons.math.stat.descriptive.summary.SumOfLogs;
025
026 /**
027 * Returns the <a href="http://www.xycoon.com/geometric_mean.htm">
028 * geometric mean </a> of the available values.
029 * <p>
030 * Uses a {@link SumOfLogs} instance to compute sum of logs and returns
031 * <code> exp( 1/n (sum of logs) ).</code> Therefore, </p>
032 * <ul>
033 * <li>If any of values are < 0, the result is <code>NaN.</code></li>
034 * <li>If all values are non-negative and less than
035 * <code>Double.POSITIVE_INFINITY</code>, but at least one value is 0, the
036 * result is <code>0.</code></li>
037 * <li>If both <code>Double.POSITIVE_INFINITY</code> and
038 * <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
039 * <code>NaN.</code></li>
040 * </ul> </p>
041 * <p>
042 * <strong>Note that this implementation is not synchronized.</strong> If
043 * multiple threads access an instance of this class concurrently, and at least
044 * one of the threads invokes the <code>increment()</code> or
045 * <code>clear()</code> method, it must be synchronized externally.</p>
046 *
047 *
048 * @version $Revision: 811827 $ $Date: 2009-09-06 11:32:50 -0400 (Sun, 06 Sep 2009) $
049 */
050 public class GeometricMean extends AbstractStorelessUnivariateStatistic implements Serializable {
051
052 /** Serializable version identifier */
053 private static final long serialVersionUID = -8178734905303459453L;
054
055 /** Wrapped SumOfLogs instance */
056 private StorelessUnivariateStatistic sumOfLogs;
057
058 /**
059 * Create a GeometricMean instance
060 */
061 public GeometricMean() {
062 sumOfLogs = new SumOfLogs();
063 }
064
065 /**
066 * Copy constructor, creates a new {@code GeometricMean} identical
067 * to the {@code original}
068 *
069 * @param original the {@code GeometricMean} instance to copy
070 */
071 public GeometricMean(GeometricMean original) {
072 super();
073 copy(original, this);
074 }
075
076 /**
077 * Create a GeometricMean instance using the given SumOfLogs instance
078 * @param sumOfLogs sum of logs instance to use for computation
079 */
080 public GeometricMean(SumOfLogs sumOfLogs) {
081 this.sumOfLogs = sumOfLogs;
082 }
083
084 /**
085 * {@inheritDoc}
086 */
087 @Override
088 public GeometricMean copy() {
089 GeometricMean result = new GeometricMean();
090 copy(this, result);
091 return result;
092 }
093
094 /**
095 * {@inheritDoc}
096 */
097 @Override
098 public void increment(final double d) {
099 sumOfLogs.increment(d);
100 }
101
102 /**
103 * {@inheritDoc}
104 */
105 @Override
106 public double getResult() {
107 if (sumOfLogs.getN() > 0) {
108 return Math.exp(sumOfLogs.getResult() / sumOfLogs.getN());
109 } else {
110 return Double.NaN;
111 }
112 }
113
114 /**
115 * {@inheritDoc}
116 */
117 @Override
118 public void clear() {
119 sumOfLogs.clear();
120 }
121
122 /**
123 * Returns the geometric mean of the entries in the specified portion
124 * of the input array.
125 * <p>
126 * See {@link GeometricMean} for details on the computing algorithm.</p>
127 * <p>
128 * Throws <code>IllegalArgumentException</code> if the array is null.</p>
129 *
130 * @param values input array containing the values
131 * @param begin first array element to include
132 * @param length the number of elements to include
133 * @return the geometric mean or Double.NaN if length = 0 or
134 * any of the values are <= 0.
135 * @throws IllegalArgumentException if the input array is null or the array
136 * index parameters are not valid
137 */
138 @Override
139 public double evaluate(
140 final double[] values, final int begin, final int length) {
141 return Math.exp(
142 sumOfLogs.evaluate(values, begin, length) / length);
143 }
144
145 /**
146 * {@inheritDoc}
147 */
148 public long getN() {
149 return sumOfLogs.getN();
150 }
151
152 /**
153 * <p>Sets the implementation for the sum of logs.</p>
154 * <p>This method must be activated before any data has been added - i.e.,
155 * before {@link #increment(double) increment} has been used to add data;
156 * otherwise an IllegalStateException will be thrown.</p>
157 *
158 * @param sumLogImpl the StorelessUnivariateStatistic instance to use
159 * for computing the log sum
160 * @throws IllegalStateException if data has already been added
161 * (i.e if n > 0)
162 */
163 public void setSumLogImpl(
164 StorelessUnivariateStatistic sumLogImpl) {
165 checkEmpty();
166 this.sumOfLogs = sumLogImpl;
167 }
168
169 /**
170 * Returns the currently configured sum of logs implementation
171 *
172 * @return the StorelessUnivariateStatistic implementing the log sum
173 */
174 public StorelessUnivariateStatistic getSumLogImpl() {
175 return sumOfLogs;
176 }
177
178 /**
179 * Copies source to dest.
180 * <p>Neither source nor dest can be null.</p>
181 *
182 * @param source GeometricMean to copy
183 * @param dest GeometricMean to copy to
184 * @throws NullPointerException if either source or dest is null
185 */
186 public static void copy(GeometricMean source, GeometricMean dest) {
187 dest.sumOfLogs = source.sumOfLogs.copy();
188 }
189
190
191 /**
192 * Throws IllegalStateException if n > 0.
193 */
194 private void checkEmpty() {
195 if (getN() > 0) {
196 throw MathRuntimeException.createIllegalStateException(
197 "{0} values have been added before statistic is configured",
198 getN());
199 }
200 }
201
202 }