uk.ac.starlink.ttools.plot2.layer

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 and Description
static interface	BinBag.Bin Describes the extent of a bin and the value it contains.

Constructor Summary

Constructors

Constructor and Description
BinBag(boolean log, double binWidth, double binPhase, Combiner combiner, double point) Constructor.

Method Summary

Modifier and Type	Method and 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 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 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