org.modeshape.common.statistic

## Class DetailedStatistics<T extends Number>

- java.lang.Object
- - org.modeshape.common.statistic.SimpleStatistics<T>
  - - org.modeshape.common.statistic.DetailedStatistics<T>

- Type Parameters:
    `T` - the number type for these statistics

      @ThreadSafe
      public class DetailedStatistics<T extends Number>
      extends SimpleStatistics<T>

  Encapsulation of the statistics for a series of values to which new values are frequently added. The statistics include the `minimum`, `maximum`, `total (aggregate sum)`, `mean (average)`, `median`, `standard deviation` and the `histogram` of the values.

  This class uses an efficient running calculation of the mean and standard deviation that is not as susceptible to roundoff errors as other traditional algorithms. The recursive algorithm is as follows, where M is the median value, sigma is the standard deviation, and S is a variable used in the calculation of sigma:

         M(1) = x(1)
         S(1) = 0
         M(k) = M(k-1) + ( x(k) - M(k-1) ) / k
         S(k) = S(k-1) + ( x(k) - M(k-1) ) * (x(k) - M(k))

  Then, the standard deviation for n values in x is

       sigma = sqrt(S(n) / n)

  Unlike the other quantities, the median value (the value at which half of the values are greater and half the values are lower) cannot be calculated incrementally. Therefore, this class does record the values so that the median can be properly calculated. This fact should be kept in mind when performing statistics on large numbers of values.

  This class is threadsafe.

- - ### Field Summary

    - ### Fields inherited from class org.modeshape.common.statistic.SimpleStatistics

      `math`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DetailedStatistics(MathOperations<T> operations)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `doAddValue(T value)` A method that can be overridden by subclasses when `add` is called.
    `protected void` | `doReset()` Method that can be overridden by subclasses when `SimpleStatistics.reset()` is called.
    `Histogram<T>` | `getHistogram()` Return the histogram of the `values`.
    `Histogram<T>` | `getHistogram(int numSigmas)` Return the histogram of the `values`.
    `T` | `getMedian()` Return the approximate mean (average) value represented as an instance of the operand type.
    `double` | `getMedianValue()` Return the median value.
    `double` | `getStandardDeviation()` Return the standard deviation.
    `List<T>` | `getValues()` Get the values that have been recorded in these statistics.
    `String` | `toString()`

    - ### Methods inherited from class org.modeshape.common.statistic.SimpleStatistics

      `add, getCount, getLock, getMathOperations, getMaximum, getMean, getMeanValue, getMinimum, getTotal, reset`

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

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

- - ### Constructor Detail

    - #### DetailedStatistics

          public DetailedStatistics(MathOperations<T> operations)

  - ### Method Detail

    - #### getValues

          public List<T> getValues()

      Get the values that have been recorded in these statistics. The contents of this list may change if new values are `added` in another thread.
      Returns:
        the unmodifiable collection of values, in insertion order

    - #### doAddValue

          protected void doAddValue(T value)

      Description copied from class: `SimpleStatistics`
      A method that can be overridden by subclasses when `add` is called. This method is called within the write lock, and does real work. Therefore, subclasses should call this method when they overwrite it.
      Overrides:
        `doAddValue` in class `SimpleStatistics<T extends Number>`
      Parameters:
        `value` - the value already added

    - #### getMedian

          public T getMedian()

      Return the approximate mean (average) value represented as an instance of the operand type. Note that this may truncate if the operand type is not able to have the required precision. For the accurate mean, see `getMedianValue()`.
      Returns:
        the mean (average), or 0.0 if the `count` is 0

    - #### getMedianValue

          public double getMedianValue()

      Return the median value.
      Returns:
        the median value, or 0.0 if the `count` is 0
      See Also:
        `getMedian()`

    - #### getStandardDeviation

          public double getStandardDeviation()

      Return the standard deviation. The standard deviation is a measure of the variation in a series of values. Values with a lower standard deviation has less variance in the values than a series of values with a higher standard deviation.
      Returns:
        the standard deviation, or 0.0 if the `count` is 0 or if all of the values are the same.

    - #### getHistogram

          public Histogram<T> getHistogram()

      Return the histogram of the `values`. This method returns a histogram where all of the buckets are distributed normally and all have the same width. In this case, the 'numSigmas' should be set to 0. For other variations, see `getHistogram(int)`.
      Returns:
        the histogram
      See Also:
        `getHistogram(int)`

    - #### getHistogram

          public Histogram<T> getHistogram(int numSigmas)

      Return the histogram of the `values`. This method is capable of creating two kinds of histograms. The first kind is a histogram where all of the buckets are distributed normally and all have the same width. In this case, the 'numSigmas' should be set to 0. See `getHistogram()`.

      The second kind of histogram is more useful when most of the data that is clustered near one value. This histogram is focused around the values that are up to 'numSigmas' above and below the `median`, and all values outside of this range are placed in the first and last bucket.

      Parameters:
        `numSigmas` - the number of standard deviations from the `median`, or 0 if the buckets of the histogram should be evenly distributed
      Returns:
        the histogram
      See Also:
        `getHistogram()`

    - #### doReset

          protected void doReset()

      Description copied from class: `SimpleStatistics`
      Method that can be overridden by subclasses when `SimpleStatistics.reset()` is called. This method is called while the object is locked for write and does work; therefore, the subclass should call this method.
      Overrides:
        `doReset` in class `SimpleStatistics<T extends Number>`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `SimpleStatistics<T extends Number>`

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.