Class BinBag
- java.lang.Object
-
- uk.ac.starlink.ttools.plot2.layer.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.
-
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.
-
-
-
Constructor Detail
-
BinBag
public BinBag(boolean log, double binWidth, double binPhase, Combiner combiner, double point)
Constructor. Notional bin boundaries are forlog=false
:binWidth*(0+binPhase), binWidth*(1+binPhase), ...
and forlog=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 logarithmicbinWidth
- width of each bin; this is additive for linear and multiplicative for logarithmic scalingbinPhase
- determines sub-bin boundary shifts along axis, normally in range 0..1combiner
- aggregation modepoint
- 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 coordinatedatum
- 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 histogramnorm
- normalisation modeunit
- 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 histogramnorm
- normalisation modeunit
- axis unit scalingrange
- 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 interesthi
- 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 suppliedother
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 logarithmicbinWidth
- width of each bin; this is additive for linear and multiplicative for logarithmic scalingbinPhase
- determines sub-bin boundary shifts along axis normally in range 0..1combiner
- aggregation mode- Returns:
- true iff a BinBag constructed using the given parameters would have the same behaviour as this one
-
-