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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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

Copyright (c) 2003-2013 Apache Software Foundation