Class IntStatistics

java.lang.Object
org.apache.commons.statistics.descriptive.IntStatistics
All Implemented Interfaces:
IntConsumer

public final class IntStatistics extends Object implements IntConsumer
Statistics for int values.

This class provides combinations of individual statistic implementations in the org.apache.commons.statistics.descriptive package.

Supports up to 263 (exclusive) observations. This implementation does not check for overflow of the count.

Since:
1.1
  • Field Details

    • NO_CONFIGURED_STATISTICS

      private static final String NO_CONFIGURED_STATISTICS
      Error message for non configured statistics.
      See Also:
    • UNSUPPORTED_STATISTIC

      private static final String UNSUPPORTED_STATISTIC
      Error message for an unsupported statistic.
      See Also:
    • count

      private long count
      Count of values recorded.
    • consumer

      private final IntConsumer consumer
      The consumer of values.
    • min

      private final IntMin min
      The IntMin implementation.
    • max

      private final IntMax max
      The IntMax implementation.
    • moment

      private final FirstMoment moment
      The moment implementation. May be any instance of FirstMoment. This implementation uses only the third and fourth moments.
    • sum

      private final IntSum sum
      The IntSum implementation.
    • product

      private final Product product
      The Product implementation.
    • sumOfSquares

      private final IntSumOfSquares sumOfSquares
      The IntSumOfSquares implementation.
    • sumOfLogs

      private final SumOfLogs sumOfLogs
      The SumOfLogs implementation.
    • config

      private StatisticsConfiguration config
      Configuration options for computation of statistics.
  • Constructor Details

    • IntStatistics

      IntStatistics(long count, IntMin min, IntMax max, FirstMoment moment, IntSum sum, Product product, IntSumOfSquares sumOfSquares, SumOfLogs sumOfLogs, StatisticsConfiguration config)
      Create an instance.
      Parameters:
      count - Count of values.
      min - IntMin implementation.
      max - IntMax implementation.
      moment - Moment implementation.
      sum - IntSum implementation.
      product - Product implementation.
      sumOfSquares - Sum of squares implementation.
      sumOfLogs - Sum of logs implementation.
      config - Statistics configuration.
  • Method Details

    • composeAsInt

      private static IntConsumer composeAsInt(DoubleConsumer... consumers)
      Chain the consumers into a single composite IntConsumer. Ignore any null consumer.
      Parameters:
      consumers - Consumers.
      Returns:
      a composed consumer (or null)
    • of

      public static IntStatistics of(Statistic... statistics)
      Returns a new instance configured to compute the specified statistics.

      The statistics will be empty and so will return the default values for each computed statistic.

      Parameters:
      statistics - Statistics to compute.
      Returns:
      the instance
      Throws:
      IllegalArgumentException - if there are no statistics to compute.
    • of

      public static IntStatistics of(Set<Statistic> statistics, int... values)
      Returns a new instance configured to compute the specified statistics populated using the input values.

      Use this method to create an instance populated with a (variable) array of int[] data:

       IntStatistics stats = IntStatistics.of(
           EnumSet.of(Statistic.MIN, Statistic.MAX),
           1, 1, 2, 3, 5, 8, 13);
       
      Parameters:
      statistics - Statistics to compute.
      values - Values.
      Returns:
      the instance
      Throws:
      IllegalArgumentException - if there are no statistics to compute.
    • builder

      public static IntStatistics.Builder builder(Statistic... statistics)
      Returns a new builder configured to create instances to compute the specified statistics.

      Use this method to create an instance populated with an array of int[] data using the IntStatistics.Builder.build(int...) method:

       int[] data = ...
       IntStatistics stats = IntStatistics.builder(
           Statistic.MIN, Statistic.MAX, Statistic.VARIANCE)
           .build(data);
       

      The builder can be used to create multiple instances of IntStatistics to be used in parallel, or on separate arrays of int[] data. These may be combined. For example:

       int[][] data = ...
       IntStatistics.Builder builder = IntStatistics.builder(
           Statistic.MIN, Statistic.MAX, Statistic.VARIANCE);
       IntStatistics stats = Arrays.stream(data)
           .parallel()
           .map(builder::build)
           .reduce(IntStatistics::combine)
           .get();
       

      The builder can be used to create a Collector for repeat use on multiple data:

      
       IntStatistics.Builder builder = IntStatistics.builder(
           Statistic.MIN, Statistic.MAX, Statistic.VARIANCE);
       Collector<int[], IntStatistics, IntStatistics> collector =
           Collector.of(builder::build,
                        (s, d) -> s.combine(builder.build(d)),
                        IntStatistics::combine);
      
       // Repeated
       int[][] data = ...
       IntStatistics stats = Arrays.stream(data).collect(collector);
       
      Parameters:
      statistics - Statistics to compute.
      Returns:
      the builder
      Throws:
      IllegalArgumentException - if there are no statistics to compute.
    • accept

      public void accept(int value)
      Updates the state of the statistics to reflect the addition of value.
      Specified by:
      accept in interface IntConsumer
      Parameters:
      value - Value.
    • getCount

      public long getCount()
      Return the count of values recorded.
      Returns:
      the count of values
    • isSupported

      public boolean isSupported(Statistic statistic)
      Check if the specified statistic is supported.

      Note: This method will not return false if the argument is null.

      Parameters:
      statistic - Statistic.
      Returns:
      true if supported
      Throws:
      NullPointerException - if the statistic is null
      See Also:
    • getAsDouble

      public double getAsDouble(Statistic statistic)
      Gets the value of the specified statistic as a double.
      Parameters:
      statistic - Statistic.
      Returns:
      the value
      Throws:
      IllegalArgumentException - if the statistic is not supported
      See Also:
    • getAsInt

      public int getAsInt(Statistic statistic)
      Gets the value of the specified statistic as an int.

      Use this method to access the int result for exact integer statistics, for example Statistic.MIN.

      Note: This method may throw an ArithmeticException if the result overflows an int.

      Parameters:
      statistic - Statistic.
      Returns:
      the value
      Throws:
      IllegalArgumentException - if the statistic is not supported
      ArithmeticException - if the result overflows an int or is not finite
      See Also:
    • getAsLong

      public long getAsLong(Statistic statistic)
      Gets the value of the specified statistic as a long.

      Use this method to access the long result for exact integer statistics, for example Statistic.SUM for a count less than or equal to 232.

      Note: This method may throw an ArithmeticException if the result overflows an long.

      Parameters:
      statistic - Statistic.
      Returns:
      the value
      Throws:
      IllegalArgumentException - if the statistic is not supported
      ArithmeticException - if the result overflows an long or is not finite
      See Also:
    • getAsBigInteger

      public BigInteger getAsBigInteger(Statistic statistic)
      Gets the value of the specified statistic as a BigInteger.

      Use this method to access the BigInteger result for exact integer statistics, for example Statistic.SUM_OF_SQUARES.

      Note: This method may throw an ArithmeticException if the result is not finite.

      Parameters:
      statistic - Statistic.
      Returns:
      the value
      Throws:
      IllegalArgumentException - if the statistic is not supported
      ArithmeticException - if the result is not finite
      See Also:
    • getResult

      public StatisticResult getResult(Statistic statistic)
      Gets a supplier for the value of the specified statistic.

      The returned function will supply the correct result after calls to accept or combine further values into this instance.

      This method can be used to perform a one-time look-up of the statistic function to compute statistics as values are dynamically added.

      Parameters:
      statistic - Statistic.
      Returns:
      the supplier
      Throws:
      IllegalArgumentException - if the statistic is not supported
      See Also:
    • getGeometricMean

      private StatisticResult getGeometricMean()
      Gets the geometric mean.
      Returns:
      a geometric mean supplier (or null if unsupported)
    • getKurtosis

      private StatisticResult getKurtosis()
      Gets the kurtosis.
      Returns:
      a kurtosis supplier (or null if unsupported)
    • getMean

      private StatisticResult getMean()
      Gets the mean.
      Returns:
      a mean supplier (or null if unsupported)
    • getSkewness

      private StatisticResult getSkewness()
      Gets the skewness.
      Returns:
      a skewness supplier (or null if unsupported)
    • getStandardDeviation

      private StatisticResult getStandardDeviation()
      Gets the standard deviation.
      Returns:
      a standard deviation supplier (or null if unsupported)
    • getVariance

      private StatisticResult getVariance()
      Gets the variance.
      Returns:
      a variance supplier (or null if unsupported)
    • getVarianceOrStd

      private StatisticResult getVarianceOrStd(boolean std)
      Gets the variance or standard deviation.
      Parameters:
      std - Flag to control if the statistic is the standard deviation.
      Returns:
      a variance/standard deviation supplier (or null if unsupported)
    • combine

      public IntStatistics combine(IntStatistics other)
      Combines the state of the other statistics into this one. Only this instance is modified by the combine operation.

      The other instance must be compatible. This is true if the other instance returns true for isSupported(Statistic) for all values of the Statistic enum which are supported by this instance.

      Note that this operation is not symmetric. It may be possible to perform a.combine(b) but not b.combine(a). In the event that the other instance is not compatible then an exception is raised before any state is modified.

      Parameters:
      other - Another set of statistics to be combined.
      Returns:
      this instance after combining other.
      Throws:
      IllegalArgumentException - if the other is not compatible
    • setConfiguration

      public IntStatistics setConfiguration(StatisticsConfiguration v)
      Sets the statistics configuration.

      These options only control the final computation of statistics. The configuration will not affect compatibility between instances during a combine operation.

      Note: These options will affect any future computation of statistics. Supplier functions that have been previously created will not be updated with the new configuration.

      Parameters:
      v - Value.
      Returns:
      this instance
      Throws:
      NullPointerException - if the value is null
      See Also: