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

## Class FirstMoment

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

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

Direct Known Subclasses:
  SecondMoment

     class FirstMoment
    extends AbstractStorelessUnivariateStatistic
    implements java.io.Serializable

Computes the first moment (arithmetic mean). Uses the definitional formula:

mean = sum(x_i) / n

where `n` is the number of observations.

To limit numeric errors, the value of the statistic is computed using the following recursive updating algorithm:

1. Initialize `m =` the first value
2. For each additional value, update using
   `m = m + (new value - m) / (number of observations)`

Returns `Double.NaN` if the dataset is empty.

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: FirstMoment.java 1416643 2012-12-03 19:37:14Z tn $

### Field Summary

Fields
`protected double` `dev` Deviation of most recently added value from previous first moment.
`protected double` `m1` First moment of values that have been added
`protected long` `n` Count of values that have been added
`protected double` `nDev` Deviation of most recently added value from previous first moment, normalized by previous sample size.
`private static long` `serialVersionUID` Serializable version identifier

### Constructor Summary

Constructors
Constructor and Description
`FirstMoment()` Create a FirstMoment instance
`FirstMoment(FirstMoment original)` Copy constructor, creates a new `FirstMoment` identical to the `original`

### Method Summary

Methods
`void` `clear()` Clears the internal state of the Statistic
`FirstMoment` `copy()` Returns a copy of the statistic with the same internal state.
`static void` `copy(FirstMoment source, FirstMoment dest)` Copies source to dest.
`long` `getN()` Returns the number of values that have been added.
`double` `getResult()` Returns the current value of the Statistic.
`void` `increment(double d)` Updates the internal state of the statistic to reflect the addition of the new value.

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

`equals, evaluate, 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

#### n

    protected long n

Count of values that have been added

#### m1

    protected double m1

First moment of values that have been added

#### dev

    protected double dev

Deviation of most recently added value from previous first moment. Retained to prevent repeated computation in higher order moments.

#### nDev

    protected double nDev

Deviation of most recently added value from previous first moment, normalized by previous sample size. Retained to prevent repeated computation in higher order moments

### Constructor Detail

#### FirstMoment

    public FirstMoment()

Create a FirstMoment instance

#### FirstMoment

    public FirstMoment(FirstMoment original)
                throws NullArgumentException

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

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

### Method Detail

#### 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.

#### clear

    public void clear()

Clears the internal state of the Statistic

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

#### 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.

#### getN

    public long getN()

Returns the number of values that have been added.

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

#### copy

    public FirstMoment 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

#### copy

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

Copies source to dest.

Neither source nor dest can be null.

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