Class BinBag

java.lang.Object
uk.ac.starlink.ttools.plot2.layer.BinBag

public class BinBag extends 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 
    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

    Modifier and Type
    Method
    Description
    void
    add(BinBag other)
    Adds the contents of another compatible BinBag to this one.
    Iterator<double[]>
    barIterator(double lo, double hi)
    Iterates over all the bins defined by this bin bag in a given data interval.
    Returns a sorted iterator over all bins with non-zero values in the range over which samples were presented.
    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
    Returns the number of non-empty bins in this bag.
    double
    Returns the bin width used by this histogram model.
    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 Details

    • 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 Details

    • 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 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 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 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