Class DoubleStatistics

  • All Implemented Interfaces:
    java.util.function.DoubleConsumer

    public final class DoubleStatistics
    extends java.lang.Object
    implements java.util.function.DoubleConsumer
    Statistics for double 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 Detail

      • NO_CONFIGURED_STATISTICS

        private static final java.lang.String NO_CONFIGURED_STATISTICS
        Error message for non configured statistics.
        See Also:
        Constant Field Values
      • UNSUPPORTED_STATISTIC

        private static final java.lang.String UNSUPPORTED_STATISTIC
        Error message for an unsupported statistic.
        See Also:
        Constant Field Values
      • count

        private long count
        Count of values recorded.
      • consumer

        private final java.util.function.DoubleConsumer consumer
        The consumer of values.
      • min

        private final Min min
        The Min implementation.
      • max

        private final Max max
        The Max implementation.
      • sum

        private final Sum sum
        The Sum implementation.
    • Constructor Detail

      • DoubleStatistics

        DoubleStatistics​(long count,
                         Min min,
                         Max max,
                         FirstMoment moment,
                         Sum sum,
                         Product product,
                         SumOfSquares sumOfSquares,
                         SumOfLogs sumOfLogs,
                         StatisticsConfiguration config)
        Create an instance.
        Parameters:
        count - Count of values.
        min - Min implementation.
        max - Max implementation.
        moment - Moment implementation.
        sum - Sum implementation.
        product - Product implementation.
        sumOfSquares - Sum of squares implementation.
        sumOfLogs - Sum of logs implementation.
        config - Statistics configuration.
    • Method Detail

      • of

        public static DoubleStatistics 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:
        java.lang.IllegalArgumentException - if there are no statistics to compute.
      • of

        public static DoubleStatistics of​(java.util.Set<Statistic> statistics,
                                          double... 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 double[] data:

         DoubleStatistics stats = DoubleStatistics.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:
        java.lang.IllegalArgumentException - if there are no statistics to compute.
      • builder

        public static DoubleStatistics.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 double[] data using the DoubleStatistics.Builder.build(double...) method:

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

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

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

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

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

        public void accept​(double value)
        Updates the state of the statistics to reflect the addition of value.
        Specified by:
        accept in interface java.util.function.DoubleConsumer
        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:
        java.lang.NullPointerException - if the statistic is null
        See Also:
        getAsDouble(Statistic)
      • getAsDouble

        public double getAsDouble​(Statistic statistic)
        Gets the value of the specified statistic as a double.
        Parameters:
        statistic - Statistic.
        Returns:
        the value
        Throws:
        java.lang.IllegalArgumentException - if the statistic is not supported
        See Also:
        isSupported(Statistic), getResult(Statistic)
      • 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:
        java.lang.IllegalArgumentException - if the statistic is not supported
        See Also:
        isSupported(Statistic), getAsDouble(Statistic)
      • 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)
      • combine

        public DoubleStatistics combine​(DoubleStatistics 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:
        java.lang.IllegalArgumentException - if the other is not compatible
      • setConfiguration

        public DoubleStatistics 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:
        java.lang.NullPointerException - if the value is null
        See Also:
        getResult(Statistic)