uk.ac.starlink.ttools.plot2

Class HistoRanger

java.lang.Object

uk.ac.starlink.ttools.plot2.HistoRanger

All Implemented Interfaces:

Ranger

public class HistoRanger
extends Object
implements Ranger

Histogram-capable Ranger implementation. Evenly sampled values from the input data stream are stored so that scaling based on the detailed distribution of the data, rather than just its minimum and maximum values, can be achieved.

This ranger is not intended to calculate arithmetically accurate quantile values, but it's hopefully good enough to come up with colour maps. The current implementation does a reasonable job of adaptive sampling, but for large datasets (greater than the storage capacity) it may be biassed, especially the add(uk.ac.starlink.ttools.plot2.Ranger) method required for range calculation in parallel.

Since:

21 Mar 2019

Author:

Mark Taylor

Constructor Summary

Constructors

Constructor and Description
HistoRanger(int nStore, int nQuantile) Constructor.

Method Summary

Modifier and Type	Method and Description
void	add(Ranger other) Merges the contents of the supplied ranger into this one.
static boolean	canScaleHistograms(Span span) Indicates whether a given span can be used to scale histograms.
Ranger	createCompatibleRanger() Returns a Ranger instance that is compatible with this one.
Span	createSpan() Returns an object characterising the range of data submitted so far.
void	submitDatum(double d) Accepts a data value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HistoRanger

public HistoRanger(int nStore,
                   int nQuantile)

Constructor. The number of samples collected and the number of quantiles can both be configured. The sample count defines the memory footprint of this object, which ought to be short lived, while the quantile count defines the memory footprint of any span objects created, which may be long-lived.

Parameters:

nStore - maximum number of samples to store

nQuantile - maximum number of quantiles on which to base scaling

Method Detail

submitDatum

public void submitDatum(double d)

Description copied from interface: Ranger

Accepts a data value.

Specified by:

submitDatum in interface Ranger

Parameters:

d - datum

add

public void add(Ranger other)

Description copied from interface: Ranger

Merges the contents of the supplied ranger into this one. The effect is as if all the results accumulated into other had been accumulated into this one. The effect on the supplied other is undefined.

The supplied ranger is assumed to be compatible with this one, which probably means created in the same way. If not, some RuntimeException such as a ClassCastException may result.

Specified by:

add in interface Ranger

Parameters:

other - compatible ranger instance

createCompatibleRanger

public Ranger createCompatibleRanger()

Description copied from interface: Ranger

Returns a Ranger instance that is compatible with this one. It has no content (does not copy any data from this one), but the two may be merged using the Ranger.add(uk.ac.starlink.ttools.plot2.Ranger) method.

Specified by:

createCompatibleRanger in interface Ranger

Returns:

new compatible ranger instance

createSpan

public Span createSpan()

Description copied from interface: Ranger

Returns an object characterising the range of data submitted so far. This should not be called while another thread might be calling Ranger.submitDatum(double).

Specified by:

createSpan in interface Ranger

Returns:

span of accumulated data

canScaleHistograms

public static boolean canScaleHistograms(Span span)

Indicates whether a given span can be used to scale histograms. Iff true, the span's Span.createScaler(uk.ac.starlink.ttools.plot2.Scaling, uk.ac.starlink.ttools.plot2.Subrange) method will work with a Scaling argument like Scaling.HISTO. This method relies on this class's knowledge of its implementation details.

Parameters:

span - span instance to test

Returns:

true iff span is histogram-capable