# 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`
`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

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.
`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.
`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 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