Class BinBag


  • public class BinBag
    extends java.lang.Object
    Data model for a one-dimensional histogram. Linear and logarithmic axis scaling are supported.
    Since:
    8 Jan 2014
    Author:
    Mark Taylor
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static interface  BinBag.Bin
      Describes the extent of a bin and the value it contains.
    • Constructor Summary

      Constructors 
      Constructor Description
      BinBag​(boolean log, double binWidth, double binPhase, Combiner combiner, double point)
      Constructor.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void add​(BinBag other)
      Adds the contents of another compatible BinBag to this one.
      java.util.Iterator<double[]> barIterator​(double lo, double hi)
      Iterates over all the bins defined by this bin bag in a given data interval.
      java.util.Iterator<BinBag.Bin> binIterator​(Cumulation cumul, Normalisation norm, Unit unit)
      Returns a sorted iterator over all bins with non-zero values in the range over which samples were presented.
      java.util.Iterator<BinBag.Bin> binIterator​(Cumulation cumul, Normalisation norm, Unit unit, double[] range)
      Returns a sorted iterator over all bins with non-zero values in the range over which samples were presented, perhaps extended over a given range.
      int getBinCount()
      Returns the number of non-empty bins in this bag.
      double getBinWidth()
      Returns the bin width used by this histogram model.
      Combiner getCombiner()
      Returns this bin bag's combiner.
      boolean matches​(boolean log, double binWidth, double binPhase, Combiner combiner)
      Indicates whether the bin boundaries and aggregation mode used by this object are the same as a given bin set specification.
      void submitToBin​(double point, double datum)
      Submits a value for aggregation in the bin in which a given point falls.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • BinBag

        public BinBag​(boolean log,
                      double binWidth,
                      double binPhase,
                      Combiner combiner,
                      double point)
        Constructor. Notional bin boundaries are for log=false:
           binWidth*(0+binPhase), binWidth*(1+binPhase), ...
         
        and for log=true:
           binWidth**(0+binPhase), binWidth**(1+binPhase), ...
         

        The point parameter is used internally to determine the zero point of the bins. In principle this should make no difference to behaviour, but in case that the data is situated a very long way from 1, setting it close to the actual data point locations may avoid rounding errors.

        Parameters:
        log - false for linear axis scaling, true for logarithmic
        binWidth - width of each bin; this is additive for linear and multiplicative for logarithmic scaling
        binPhase - determines sub-bin boundary shifts along axis, normally in range 0..1
        combiner - aggregation mode
        point - representative point on axis near which bins are situated
    • Method Detail

      • submitToBin

        public void submitToBin​(double point,
                                double datum)
        Submits a value for aggregation in the bin in which a given point falls. Checking is performed; if the point is unsuitable (for instance infinite) it will be ignored.
        Parameters:
        point - axis coordinate
        datum - value to aggregate into bin value
      • binIterator

        public java.util.Iterator<BinBag.Bin> binIterator​(Cumulation cumul,
                                                          Normalisation norm,
                                                          Unit unit)
        Returns a sorted iterator over all bins with non-zero values in the range over which samples were presented.
        Parameters:
        cumul - flag for bins of a cumulative histogram
        norm - normalisation mode
        unit - axis unit scaling
        Returns:
        sorted iterator over bins
      • binIterator

        public java.util.Iterator<BinBag.Bin> binIterator​(Cumulation cumul,
                                                          Normalisation norm,
                                                          Unit unit,
                                                          double[] range)
        Returns a sorted iterator over all bins with non-zero values in the range over which samples were presented, perhaps extended over a given range.

        The purpose of the supplied extension range is to extend the number of bins returned, specifically for the purpose of cumulative histograms, where bins outside the range of the presented samples can have non-zero values. At present the range is not used to cut down the number of bins returned; that could be done to improve efficiency, though the effect is not likely to be large since bin counts are usually fairly modest.

        Parameters:
        cumul - flag for bins of a cumulative histogram
        norm - normalisation mode
        unit - axis unit scaling
        range - required range for extending data
        Returns:
        sorted iterator over bins
      • barIterator

        public java.util.Iterator<double[]> barIterator​(double lo,
                                                        double hi)
        Iterates over all the bins defined by this bin bag in a given data interval. The contents of each bin, if any, are irrelevant to this operation.
        Parameters:
        lo - lower bound of interest
        hi - upper bound of interest
        Returns:
        iterator in sequence over 2-element (low,high) bin range arrays that together cover the supplied (lo,hi) range
      • getBinWidth

        public double getBinWidth()
        Returns the bin width used by this histogram model. It's additive for linear and multiplicative for logarithmic.
        Returns:
        bin width
      • getCombiner

        public Combiner getCombiner()
        Returns this bin bag's combiner.
        Returns:
        combination mode
      • getBinCount

        public int getBinCount()
        Returns the number of non-empty bins in this bag.
        Returns:
        bin count
      • add

        public void add​(BinBag other)
        Adds the contents of another compatible BinBag to this one. The effect is as if all the data submitted to the other bag had been submitted to this one as well. The effect on the supplied other is undefined.
        Parameters:
        other - compatible accumulator
      • matches

        public boolean matches​(boolean log,
                               double binWidth,
                               double binPhase,
                               Combiner combiner)
        Indicates whether the bin boundaries and aggregation mode used by this object are the same as a given bin set specification.
        Parameters:
        log - false for linear scaling, true for logarithmic
        binWidth - width of each bin; this is additive for linear and multiplicative for logarithmic scaling
        binPhase - determines sub-bin boundary shifts along axis normally in range 0..1
        combiner - aggregation mode
        Returns:
        true iff a BinBag constructed using the given parameters would have the same behaviour as this one