org.apache.commons.math3.stat.descriptive

## Class AggregateSummaryStatistics

- java.lang.Object
- - org.apache.commons.math3.stat.descriptive.AggregateSummaryStatistics

- All Implemented Interfaces:
    Serializable, StatisticalSummary

      public class AggregateSummaryStatistics
      extends Object
      implements StatisticalSummary, Serializable

  An aggregator for `SummaryStatistics` from several data sets or data set partitions. In its simplest usage mode, the client creates an instance via the zero-argument constructor, then uses `createContributingStatistics()` to obtain a `SummaryStatistics` for each individual data set / partition. The per-set statistics objects are used as normal, and at any time the aggregate statistics for all the contributors can be obtained from this object.

  Clients with specialized requirements can use alternative constructors to control the statistics implementations and initial values used by the contributing and the internal aggregate `SummaryStatistics` objects.

  A static `aggregate(Collection)` method is also included that computes aggregate statistics directly from a Collection of SummaryStatistics instances.

  When `createContributingStatistics()` is used to create SummaryStatistics instances to be aggregated concurrently, the created instances' `AggregateSummaryStatistics.AggregatingSummaryStatistics.addValue(double)` methods must synchronize on the aggregating instance maintained by this class. In multithreaded environments, if the functionality provided by `aggregate(Collection)` is adequate, that method should be used to avoid unnecessary computation and synchronization delays.

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

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `private static class` | `AggregateSummaryStatistics.AggregatingSummaryStatistics` A SummaryStatistics that also forwards all values added to it to a second `SummaryStatistics` for aggregation.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static long` | `serialVersionUID` Serializable version identifier
    `private SummaryStatistics` | `statistics` The SummaryStatistics in which aggregate statistics are accumulated.
    `private SummaryStatistics` | `statisticsPrototype` A SummaryStatistics serving as a prototype for creating SummaryStatistics contributing to this aggregate

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AggregateSummaryStatistics()` Initializes a new AggregateSummaryStatistics with default statistics implementations.
    `AggregateSummaryStatistics(SummaryStatistics prototypeStatistics)` Initializes a new AggregateSummaryStatistics with the specified statistics object as a prototype for contributing statistics and for the internal aggregate statistics.
    `AggregateSummaryStatistics(SummaryStatistics prototypeStatistics, SummaryStatistics initialStatistics)` Initializes a new AggregateSummaryStatistics with the specified statistics object as a prototype for contributing statistics and for the internal aggregate statistics.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static StatisticalSummaryValues` | `aggregate(Collection<SummaryStatistics> statistics)` Computes aggregate summary statistics.
    `SummaryStatistics` | `createContributingStatistics()` Creates and returns a `SummaryStatistics` whose data will be aggregated with those of this `AggregateSummaryStatistics`.
    `double` | `getGeometricMean()` Returns the geometric mean of all the aggregated data.
    `double` | `getMax()` Returns the maximum of the available values
    `double` | `getMean()` Returns the arithmetic mean of the available values
    `double` | `getMin()` Returns the minimum of the available values
    `long` | `getN()` Returns the number of available values
    `double` | `getSecondMoment()` Returns a statistic related to the Second Central Moment.
    `double` | `getStandardDeviation()` Returns the standard deviation of the available values.
    `double` | `getSum()` Returns the sum of the values that have been added to Univariate.
    `StatisticalSummary` | `getSummary()` Return a `StatisticalSummaryValues` instance reporting current aggregate statistics.
    `double` | `getSumOfLogs()` Returns the sum of the logs of all the aggregated data.
    `double` | `getSumsq()` Returns the sum of the squares of all the aggregated data.
    `double` | `getVariance()` Returns the variance of the available values.

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

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

- - ### Field Detail

    - #### serialVersionUID

          private static final long serialVersionUID

      Serializable version identifier
      See Also:
        Constant Field Values

    - #### statisticsPrototype

          private final SummaryStatistics statisticsPrototype

      A SummaryStatistics serving as a prototype for creating SummaryStatistics contributing to this aggregate

    - #### statistics

          private final SummaryStatistics statistics

      The SummaryStatistics in which aggregate statistics are accumulated.

  - ### Constructor Detail

    - #### AggregateSummaryStatistics

          public AggregateSummaryStatistics()

      Initializes a new AggregateSummaryStatistics with default statistics implementations.

    - #### AggregateSummaryStatistics

          public AggregateSummaryStatistics(SummaryStatistics prototypeStatistics)
                                     throws NullArgumentException

      Initializes a new AggregateSummaryStatistics with the specified statistics object as a prototype for contributing statistics and for the internal aggregate statistics. This provides for customized statistics implementations to be used by contributing and aggregate statistics.
      Parameters:
        `prototypeStatistics` - a `SummaryStatistics` serving as a prototype both for the internal aggregate statistics and for contributing statistics obtained via the `createContributingStatistics()` method. Being a prototype means that other objects are initialized by copying this object's state. If `null`, a new, default statistics object is used. Any statistic values in the prototype are propagated to contributing statistics objects and (once) into these aggregate statistics.
      Throws:
        `NullArgumentException` - if prototypeStatistics is null
      See Also:
        `createContributingStatistics()`

    - #### AggregateSummaryStatistics

          public AggregateSummaryStatistics(SummaryStatistics prototypeStatistics,
                                    SummaryStatistics initialStatistics)

      Initializes a new AggregateSummaryStatistics with the specified statistics object as a prototype for contributing statistics and for the internal aggregate statistics. This provides for different statistics implementations to be used by contributing and aggregate statistics and for an initial state to be supplied for the aggregate statistics.
      Parameters:
        `prototypeStatistics` - a `SummaryStatistics` serving as a prototype both for the internal aggregate statistics and for contributing statistics obtained via the `createContributingStatistics()` method. Being a prototype means that other objects are initialized by copying this object's state. If `null`, a new, default statistics object is used. Any statistic values in the prototype are propagated to contributing statistics objects, but not into these aggregate statistics.
        `initialStatistics` - a `SummaryStatistics` to serve as the internal aggregate statistics object. If `null`, a new, default statistics object is used.
      See Also:
        `createContributingStatistics()`

  - ### Method Detail

    - #### getMax

          public double getMax()

      Returns the maximum of the available values. This version returns the maximum over all the aggregated data.
      Specified by:
        `getMax` in interface `StatisticalSummary`
      Returns:
        The max or Double.NaN if no values have been added.
      See Also:
        `StatisticalSummary.getMax()`

    - #### getMean

          public double getMean()

      Returns the arithmetic mean of the available values. This version returns the mean of all the aggregated data.
      Specified by:
        `getMean` in interface `StatisticalSummary`
      Returns:
        The mean or Double.NaN if no values have been added.
      See Also:
        `StatisticalSummary.getMean()`

    - #### getMin

          public double getMin()

      Returns the minimum of the available values. This version returns the minimum over all the aggregated data.
      Specified by:
        `getMin` in interface `StatisticalSummary`
      Returns:
        The min or Double.NaN if no values have been added.
      See Also:
        `StatisticalSummary.getMin()`

    - #### getN

          public long getN()

      Returns the number of available values. This version returns a count of all the aggregated data.
      Specified by:
        `getN` in interface `StatisticalSummary`
      Returns:
        The number of available values
      See Also:
        `StatisticalSummary.getN()`

    - #### getStandardDeviation

          public double getStandardDeviation()

      Returns the standard deviation of the available values.. This version returns the standard deviation of all the aggregated data.
      Specified by:
        `getStandardDeviation` in interface `StatisticalSummary`
      Returns:
        The standard deviation, Double.NaN if no values have been added or 0.0 for a single value set.
      See Also:
        `StatisticalSummary.getStandardDeviation()`

    - #### getSum

          public double getSum()

      Returns the sum of the values that have been added to Univariate.. This version returns a sum of all the aggregated data.
      Specified by:
        `getSum` in interface `StatisticalSummary`
      Returns:
        The sum or Double.NaN if no values have been added
      See Also:
        `StatisticalSummary.getSum()`

    - #### getVariance

          public double getVariance()

      Returns the variance of the available values.. This version returns the variance of all the aggregated data.
      Specified by:
        `getVariance` in interface `StatisticalSummary`
      Returns:
        The variance, Double.NaN if no values have been added or 0.0 for a single value set.
      See Also:
        `StatisticalSummary.getVariance()`

    - #### getSumOfLogs

          public double getSumOfLogs()

      Returns the sum of the logs of all the aggregated data.
      Returns:
        the sum of logs
      See Also:
        `SummaryStatistics.getSumOfLogs()`

    - #### getGeometricMean

          public double getGeometricMean()

      Returns the geometric mean of all the aggregated data.
      Returns:
        the geometric mean
      See Also:
        `SummaryStatistics.getGeometricMean()`

    - #### getSumsq

          public double getSumsq()

      Returns the sum of the squares of all the aggregated data.
      Returns:
        The sum of squares
      See Also:
        `SummaryStatistics.getSumsq()`

    - #### getSecondMoment

          public double getSecondMoment()

      Returns a statistic related to the Second Central Moment. Specifically, what is returned is the sum of squared deviations from the sample mean among the all of the aggregated data.
      Returns:
        second central moment statistic
      See Also:
        `SummaryStatistics.getSecondMoment()`

    - #### getSummary

          public StatisticalSummary getSummary()

      Return a `StatisticalSummaryValues` instance reporting current aggregate statistics.
      Returns:
        Current values of aggregate statistics

    - #### createContributingStatistics

          public SummaryStatistics createContributingStatistics()

      Creates and returns a `SummaryStatistics` whose data will be aggregated with those of this `AggregateSummaryStatistics`.
      Returns:
        a `SummaryStatistics` whose data will be aggregated with those of this `AggregateSummaryStatistics`. The initial state is a copy of the configured prototype statistics.

    - #### aggregate

          public static StatisticalSummaryValues aggregate(Collection<SummaryStatistics> statistics)

      Computes aggregate summary statistics. This method can be used to combine statistics computed over partitions or subsamples - i.e., the StatisticalSummaryValues returned should contain the same values that would have been obtained by computing a single StatisticalSummary over the combined dataset.

      Returns null if the collection is empty or null.

      Parameters:
        `statistics` - collection of SummaryStatistics to aggregate
      Returns:
        summary statistics for the combined dataset

Copyright (c) 2003-2013 Apache Software Foundation