Class Histogram


  • public final class Histogram
    extends Object

    Histogram for tracking the frequency of observations of values below interval upper bounds.

    This class is useful for recording timings across a large number of observations when high performance is required.

    The interval bounds are used to define the ranges of the histogram buckets. If provided bounds are [10,20,30,40,50] then there will be five buckets, accessible by index 0-4. Any value 0-10 will fall into the first interval bar, values 11-20 will fall into the second bar, and so on.

    • Constructor Detail

      • Histogram

        public Histogram​(long[] upperBounds)
        Create a new Histogram with a provided list of interval bounds.
        Parameters:
        upperBounds - of the intervals. Bounds must be provided in order least to greatest, and lowest bound must be greater than or equal to 1.
        Throws:
        IllegalArgumentException - if any of the upper bounds are less than or equal to zero
        IllegalArgumentException - if the bounds are not in order, least to greatest
    • Method Detail

      • getSize

        public int getSize()
        Size of the list of interval bars (ie: count of interval bars).
        Returns:
        size of the interval bar list.
      • getUpperBoundAt

        public long getUpperBoundAt​(int index)
        Get the upper bound of an interval for an index.
        Parameters:
        index - of the upper bound.
        Returns:
        the interval upper bound for the index.
      • getCountAt

        public long getCountAt​(int index)
        Get the count of observations at a given index.
        Parameters:
        index - of the observations counter.
        Returns:
        the count of observations at a given index.
      • addObservation

        public boolean addObservation​(long value)
        Add an observation to the histogram and increment the counter for the interval it matches.
        Parameters:
        value - for the observation to be added.
        Returns:
        return true if in the range of intervals and successfully added observation; otherwise false.
      • addObservations

        public void addObservations​(Histogram histogram)

        Add observations from another Histogram into this one.

        Histograms must have the same intervals.

        Parameters:
        histogram - from which to add the observation counts.
        Throws:
        IllegalArgumentException - if interval count or values do not match exactly
      • clear

        public void clear()
        Clear the list of interval counters
      • getCount

        public long getCount()
        Count total number of recorded observations.
        Returns:
        the total number of recorded observations.
      • getMin

        public long getMin()
        Get the minimum observed value.
        Returns:
        the minimum value observed.
      • getMax

        public long getMax()
        Get the maximum observed value.
        Returns:
        the maximum of the observed values;
      • getMean

        public BigDecimal getMean()

        Calculate the mean of all recorded observations.

        The mean is calculated by summing the mid points of each interval multiplied by the count for that interval, then dividing by the total count of observations. The max and min are considered for adjusting the top and bottom bin when calculating the mid point, this minimises skew if the observed values are very far away from the possible histogram values.

        Returns:
        the mean of all recorded observations.
      • getTwoNinesUpperBound

        public long getTwoNinesUpperBound()
        Calculate the upper bound within which 99% of observations fall.
        Returns:
        the upper bound for 99% of observations.
      • getFourNinesUpperBound

        public long getFourNinesUpperBound()
        Calculate the upper bound within which 99.99% of observations fall.
        Returns:
        the upper bound for 99.99% of observations.
      • getUpperBoundForFactor

        public long getUpperBoundForFactor​(double factor)

        Get the interval upper bound for a given factor of the observation population.

        Note this does not get the actual percentile measurement, it only gets the bucket

        Parameters:
        factor - representing the size of the population.
        Returns:
        the interval upper bound.
        Throws:
        IllegalArgumentException - if factor < 0.0 or factor > 1.0