org.apache.commons.math3.stat.descriptive.moment

## Class GeometricMean

- java.lang.Object
- - org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic
  - - org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic
    - - org.apache.commons.math3.stat.descriptive.moment.GeometricMean

All Implemented Interfaces:
  java.io.Serializable, StorelessUnivariateStatistic, UnivariateStatistic, MathArrays.Function

    public class GeometricMean
    extends AbstractStorelessUnivariateStatistic
    implements java.io.Serializable

Returns the geometric mean of the available values.

Uses a `SumOfLogs` instance to compute sum of logs and returns `exp( 1/n (sum of logs) ).` Therefore,

- If any of values are < 0, the result is `NaN.`
- If all values are non-negative and less than `Double.POSITIVE_INFINITY`, but at least one value is 0, the result is `0.`
- If both `Double.POSITIVE_INFINITY` and `Double.NEGATIVE_INFINITY` are among the values, the result is `NaN.`

Note that this implementation is not synchronized. If multiple threads access an instance of this class concurrently, and at least one of the threads invokes the `increment()` or `clear()` method, it must be synchronized externally.

Version:
  $Id: GeometricMean.java 1416643 2012-12-03 19:37:14Z tn $
See Also:
  Serialized Form

### Field Summary

Fields
`private static long` `serialVersionUID` Serializable version identifier
`private StorelessUnivariateStatistic` `sumOfLogs` Wrapped SumOfLogs instance

### Constructor Summary

Constructors
Constructor and Description
`GeometricMean()` Create a GeometricMean instance
`GeometricMean(GeometricMean original)` Copy constructor, creates a new `GeometricMean` identical to the `original`
`GeometricMean(SumOfLogs sumOfLogs)` Create a GeometricMean instance using the given SumOfLogs instance

### Method Summary

Methods
`private void` `checkEmpty()` Throws MathIllegalStateException if n > 0.
`void` `clear()` Clears the internal state of the Statistic
`GeometricMean` `copy()` Returns a copy of the statistic with the same internal state.
`static void` `copy(GeometricMean source, GeometricMean dest)` Copies source to dest.
`double` `evaluate(double[] values, int begin, int length)` Returns the geometric mean of the entries in the specified portion of the input array.
`long` `getN()` Returns the number of values that have been added.
`double` `getResult()` Returns the current value of the Statistic.
`StorelessUnivariateStatistic` `getSumLogImpl()` Returns the currently configured sum of logs implementation
`void` `increment(double d)` Updates the internal state of the statistic to reflect the addition of the new value.
`void` `setSumLogImpl(StorelessUnivariateStatistic sumLogImpl)` Sets the implementation for the sum of logs.

### Methods inherited from class org.apache.commons.math3.stat.descriptive.AbstractStorelessUnivariateStatistic

`equals, evaluate, hashCode, incrementAll, incrementAll`

### Methods inherited from class org.apache.commons.math3.stat.descriptive.AbstractUnivariateStatistic

`evaluate, getData, getDataRef, setData, setData, test, test, test, test`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### serialVersionUID

    private static final long serialVersionUID

Serializable version identifier

See Also:
  Constant Field Values

#### sumOfLogs

    private StorelessUnivariateStatistic sumOfLogs

Wrapped SumOfLogs instance

### Constructor Detail

#### GeometricMean

    public GeometricMean()

Create a GeometricMean instance

#### GeometricMean

    public GeometricMean(GeometricMean original)
                  throws NullArgumentException

Copy constructor, creates a new `GeometricMean` identical to the `original`

Parameters:
  `original` - the `GeometricMean` instance to copy
Throws:
  `NullArgumentException` - if original is null

#### GeometricMean

    public GeometricMean(SumOfLogs sumOfLogs)

Create a GeometricMean instance using the given SumOfLogs instance

Parameters:
  `sumOfLogs` - sum of logs instance to use for computation

### Method Detail

#### copy

    public GeometricMean copy()

Returns a copy of the statistic with the same internal state.

Specified by:
  `copy` in interface `StorelessUnivariateStatistic`
Specified by:
  `copy` in interface `UnivariateStatistic`
Specified by:
  `copy` in class `AbstractStorelessUnivariateStatistic`
Returns:
  a copy of the statistic

#### increment

    public void increment(double d)

Updates the internal state of the statistic to reflect the addition of the new value.

Specified by:
  `increment` in interface `StorelessUnivariateStatistic`
Specified by:
  `increment` in class `AbstractStorelessUnivariateStatistic`
Parameters:
  `d` - the new value.

#### getResult

    public double getResult()

Returns the current value of the Statistic.

Specified by:
  `getResult` in interface `StorelessUnivariateStatistic`
Specified by:
  `getResult` in class `AbstractStorelessUnivariateStatistic`
Returns:
  value of the statistic, `Double.NaN` if it has been cleared or just instantiated.

#### clear

    public void clear()

Clears the internal state of the Statistic

Specified by:
  `clear` in interface `StorelessUnivariateStatistic`
Specified by:
  `clear` in class `AbstractStorelessUnivariateStatistic`

#### evaluate

    public double evaluate(double[] values,
                  int begin,
                  int length)
                    throws MathIllegalArgumentException

Returns the geometric mean of the entries in the specified portion of the input array.

See `GeometricMean` for details on the computing algorithm.

Throws `IllegalArgumentException` if the array is null.

Specified by:
  `evaluate` in interface `UnivariateStatistic`
Specified by:
  `evaluate` in interface `MathArrays.Function`
Overrides:
  `evaluate` in class `AbstractStorelessUnivariateStatistic`
Parameters:
  `values` - input array containing the values
  `begin` - first array element to include
  `length` - the number of elements to include
Returns:
  the geometric mean or Double.NaN if length = 0 or any of the values are <= 0.
Throws:
  `MathIllegalArgumentException` - if the input array is null or the array index parameters are not valid
See Also:
  `UnivariateStatistic.evaluate(double[], int, int)`

#### getN

    public long getN()

Returns the number of values that have been added.

Specified by:
  `getN` in interface `StorelessUnivariateStatistic`
Returns:
  the number of values.

#### setSumLogImpl

    public void setSumLogImpl(StorelessUnivariateStatistic sumLogImpl)
                       throws MathIllegalStateException

Sets the implementation for the sum of logs.

This method must be activated before any data has been added - i.e., before `increment` has been used to add data; otherwise an IllegalStateException will be thrown.

Parameters:
  `sumLogImpl` - the StorelessUnivariateStatistic instance to use for computing the log sum
Throws:
  `MathIllegalStateException` - if data has already been added (i.e if n > 0)

#### getSumLogImpl

    public StorelessUnivariateStatistic getSumLogImpl()

Returns the currently configured sum of logs implementation

Returns:
  the StorelessUnivariateStatistic implementing the log sum

#### copy

    public static void copy(GeometricMean source,
            GeometricMean dest)
                     throws NullArgumentException

Copies source to dest.

Neither source nor dest can be null.

Parameters:
  `source` - GeometricMean to copy
  `dest` - GeometricMean to copy to
Throws:
  `NullArgumentException` - if either source or dest is null

#### checkEmpty

    private void checkEmpty()
                     throws MathIllegalStateException

Throws MathIllegalStateException if n > 0.

Throws:
  `MathIllegalStateException` - if data has been added to this statistic