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 */
17package org.apache.commons.math.stat.descriptive.moment;
18
19import java.io.Serializable;
20
21import org.apache.commons.math.MathRuntimeException;
22import org.apache.commons.math.exception.util.LocalizedFormats;
23import org.apache.commons.math.stat.descriptive.AbstractStorelessUnivariateStatistic;
24import org.apache.commons.math.stat.descriptive.StorelessUnivariateStatistic;
25import org.apache.commons.math.stat.descriptive.summary.SumOfLogs;
26import org.apache.commons.math.util.FastMath;
27
28/**
29 * Returns the <a href="http://www.xycoon.com/geometric_mean.htm">
30 * geometric mean </a> of the available values.
31 * <p>
32 * Uses a {@link SumOfLogs} instance to compute sum of logs and returns
33 * <code> exp( 1/n  (sum of logs) ).</code>  Therefore, </p>
34 * <ul>
35 * <li>If any of values are < 0, the result is <code>NaN.</code></li>
36 * <li>If all values are non-negative and less than
37 * <code>Double.POSITIVE_INFINITY</code>,  but at least one value is 0, the
38 * result is <code>0.</code></li>
39 * <li>If both <code>Double.POSITIVE_INFINITY</code> and
40 * <code>Double.NEGATIVE_INFINITY</code> are among the values, the result is
41 * <code>NaN.</code></li>
42 * </ul> </p>
43 * <p>
44 * <strong>Note that this implementation is not synchronized.</strong> If
45 * multiple threads access an instance of this class concurrently, and at least
46 * one of the threads invokes the <code>increment()</code> or
47 * <code>clear()</code> method, it must be synchronized externally.</p>
48 *
49 *
50 * @version $Revision: 1006299 $ $Date: 2010-10-10 16:47:17 +0200 (dim. 10 oct. 2010) $
51 */
52public class GeometricMean extends AbstractStorelessUnivariateStatistic implements Serializable {
53
54    /** Serializable version identifier */
55    private static final long serialVersionUID = -8178734905303459453L;
56
57    /** Wrapped SumOfLogs instance */
58    private StorelessUnivariateStatistic sumOfLogs;
59
60    /**
61     * Create a GeometricMean instance
62     */
63    public GeometricMean() {
64        sumOfLogs = new SumOfLogs();
65    }
66
67    /**
68     * Copy constructor, creates a new {@code GeometricMean} identical
69     * to the {@code original}
70     *
71     * @param original the {@code GeometricMean} instance to copy
72     */
73    public GeometricMean(GeometricMean original) {
74        super();
75        copy(original, this);
76    }
77
78    /**
79     * Create a GeometricMean instance using the given SumOfLogs instance
80     * @param sumOfLogs sum of logs instance to use for computation
81     */
82    public GeometricMean(SumOfLogs sumOfLogs) {
83        this.sumOfLogs = sumOfLogs;
84    }
85
86    /**
87     * {@inheritDoc}
88     */
89    @Override
90    public GeometricMean copy() {
91        GeometricMean result = new GeometricMean();
92        copy(this, result);
93        return result;
94    }
95
96    /**
97     * {@inheritDoc}
98     */
99    @Override
100    public void increment(final double d) {
101        sumOfLogs.increment(d);
102    }
103
104    /**
105     * {@inheritDoc}
106     */
107    @Override
108    public double getResult() {
109        if (sumOfLogs.getN() > 0) {
110            return FastMath.exp(sumOfLogs.getResult() / sumOfLogs.getN());
111        } else {
112            return Double.NaN;
113        }
114    }
115
116    /**
117     * {@inheritDoc}
118     */
119    @Override
120    public void clear() {
121        sumOfLogs.clear();
122    }
123
124    /**
125     * Returns the geometric mean of the entries in the specified portion
126     * of the input array.
127     * <p>
128     * See {@link GeometricMean} for details on the computing algorithm.</p>
129     * <p>
130     * Throws <code>IllegalArgumentException</code> if the array is null.</p>
131     *
132     * @param values input array containing the values
133     * @param begin first array element to include
134     * @param length the number of elements to include
135     * @return the geometric mean or Double.NaN if length = 0 or
136     * any of the values are &lt;= 0.
137     * @throws IllegalArgumentException if the input array is null or the array
138     * index parameters are not valid
139     */
140    @Override
141    public double evaluate(
142        final double[] values, final int begin, final int length) {
143        return FastMath.exp(
144            sumOfLogs.evaluate(values, begin, length) / length);
145    }
146
147    /**
148     * {@inheritDoc}
149     */
150    public long getN() {
151        return sumOfLogs.getN();
152    }
153
154    /**
155     * <p>Sets the implementation for the sum of logs.</p>
156     * <p>This method must be activated before any data has been added - i.e.,
157     * before {@link #increment(double) increment} has been used to add data;
158     * otherwise an IllegalStateException will be thrown.</p>
159     *
160     * @param sumLogImpl the StorelessUnivariateStatistic instance to use
161     * for computing the log sum
162     * @throws IllegalStateException if data has already been added
163     *  (i.e if n > 0)
164     */
165    public void setSumLogImpl(
166            StorelessUnivariateStatistic sumLogImpl) {
167        checkEmpty();
168        this.sumOfLogs = sumLogImpl;
169    }
170
171    /**
172     * Returns the currently configured sum of logs implementation
173     *
174     * @return the StorelessUnivariateStatistic implementing the log sum
175     */
176    public StorelessUnivariateStatistic getSumLogImpl() {
177        return sumOfLogs;
178    }
179
180    /**
181     * Copies source to dest.
182     * <p>Neither source nor dest can be null.</p>
183     *
184     * @param source GeometricMean to copy
185     * @param dest GeometricMean to copy to
186     * @throws NullPointerException if either source or dest is null
187     */
188    public static void copy(GeometricMean source, GeometricMean dest) {
189        dest.setData(source.getDataRef());
190        dest.sumOfLogs = source.sumOfLogs.copy();
191    }
192
193
194    /**
195     * Throws IllegalStateException if n > 0.
196     */
197    private void checkEmpty() {
198        if (getN() > 0) {
199            throw MathRuntimeException.createIllegalStateException(
200                    LocalizedFormats.VALUES_ADDED_BEFORE_CONFIGURING_STATISTIC,
201                    getN());
202        }
203    }
204
205}
206