Class Combiner
- java.lang.Object
-
- uk.ac.starlink.ttools.plot2.layer.Combiner
-
- Direct Known Subclasses:
QuantileCombiner
@Equality public abstract class Combiner extends java.lang.Object
Defines the combination mode for accumulating values into a bin.Instances of this class can produce
Container
andBinList
objects into which values can be accumulated. Once populated, those objects can be interrogated to find combined values. Note that in general those accumulated results should be multiplied by the result of callingCombiner.Type.getBinFactor(double)
before use.Note that the
SUM
mode is usually sensible for unweighted values, but if the values are weighted it may be more revealing to use one of the others (likeMEAN
).- Since:
- 20 Sep 2015
- Author:
- Mark Taylor
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
Combiner.Container
Defines an object that can be used to accumulate values and retrieve a result.static class
Combiner.Type
Defines the scaling properties of a combiner.
-
Field Summary
Fields Modifier and Type Field Description static Combiner
COUNT
Calculate the number of submitted values.static Combiner
DENSITY
Calculate the density of all submitted values.static Combiner
HIT
Return 1 if any value submitted, 0 otherwise.static Combiner
MAX
Calculate the maximum of all submitted values.static Combiner
MEAN
Calculate the mean of all submitted values.static Combiner
MEDIAN
Calculate the median of all submitted values (slow).static Combiner
MIN
Calculate the minimum of all submitted values.static Combiner
SAMPLE_STDEV
Calculate the sample standard deviation of all submitted values.static Combiner
SUM
Calculate the sum of all submitted values.static Combiner
WEIGHTED_DENSITY
Calculate the weighted density of all submitted values.
-
Constructor Summary
Constructors Modifier Constructor Description protected
Combiner(java.lang.String name, java.lang.String description, Combiner.Type type, boolean hasBigBin)
Constructor.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Modifier and Type Method Description abstract ArrayBinList
createArrayBinList(int size)
May be able to create a bin list suitable for non-sparse, moderate-sized index ranges.abstract uk.ac.starlink.table.ValueInfo
createCombinedInfo(uk.ac.starlink.table.ValueInfo info, Unit scaleUnit)
Returns a metadata object that describes the result of applying this combiner to data described by a given metadata object.abstract Combiner.Container
createContainer()
Creates an object which can be used to accumulate values.static BinList
createDefaultBinList(Combiner combiner, long size)
Returns a BinList implementation suitable for a given number of bins and a given combiner.java.lang.String
getDescription()
Returns a short textual description of this combiner.static Combiner[]
getKnownCombiners()
Returns a list of the known general purpose instances of this class.java.lang.String
getName()
Returns this combiner's name.Combiner.Type
getType()
Indicates the aggregation type.boolean
hasBigBin()
Indicates whether the bin objects used by this combiner are large.java.lang.String
toString()
-
-
-
Field Detail
-
COUNT
public static final Combiner COUNT
Calculate the number of submitted values.
-
DENSITY
public static final Combiner DENSITY
Calculate the density of all submitted values.
-
SUM
public static final Combiner SUM
Calculate the sum of all submitted values.
-
WEIGHTED_DENSITY
public static final Combiner WEIGHTED_DENSITY
Calculate the weighted density of all submitted values.
-
MEAN
public static final Combiner MEAN
Calculate the mean of all submitted values.
-
MEDIAN
public static final Combiner MEDIAN
Calculate the median of all submitted values (slow).
-
SAMPLE_STDEV
public static final Combiner SAMPLE_STDEV
Calculate the sample standard deviation of all submitted values.
-
MIN
public static final Combiner MIN
Calculate the minimum of all submitted values.
-
MAX
public static final Combiner MAX
Calculate the maximum of all submitted values.
-
HIT
public static final Combiner HIT
Return 1 if any value submitted, 0 otherwise.
-
-
Constructor Detail
-
Combiner
protected Combiner(java.lang.String name, java.lang.String description, Combiner.Type type, boolean hasBigBin)
Constructor.- Parameters:
name
- namedescription
- short textual descriptiontype
- defines the kind of aggregation performed; note the implementation of this class does not use this value to affect the bin results calculated by this combiner, but users of this class should make use of it to interpret the bin resultshasBigBin
- indicates whether the bins used by this combiner are large (take more memory than adouble
)
-
-
Method Detail
-
createContainer
public abstract Combiner.Container createContainer()
Creates an object which can be used to accumulate values.Note: Since many container instances may by generated (when using a HashBinList) it is desirable to keep the returned objects as small as possible. In particular, it's a good idea to make the returned objects instances of a static class, to avoid an unncecessary reference to the owner object, unless there's a really compelling reason to do otherwise.
- Returns:
- new container
-
createArrayBinList
public abstract ArrayBinList createArrayBinList(int size)
May be able to create a bin list suitable for non-sparse, moderate-sized index ranges. If a combiner implementation is able to provide an ArrayBinList implementation that should be significantly more efficient than a HashBinList, this method should return it. If not, it can return null.- Parameters:
size
- index range of required bin list- Returns:
- array-based bin list, or null
-
getName
public java.lang.String getName()
Returns this combiner's name.- Returns:
- name
-
getDescription
public java.lang.String getDescription()
Returns a short textual description of this combiner.- Returns:
- short description
-
getType
public Combiner.Type getType()
Indicates the aggregation type. This value should be used to make sense of the output bin list results.- Returns:
- aggregation type
-
hasBigBin
public boolean hasBigBin()
Indicates whether the bin objects used by this combiner are large. Large means, roughly, take more memory than adouble
. This flag may be used to decide whether to compact bin list results.- Returns:
- true if this combiner uses big bins
-
createCombinedInfo
public abstract uk.ac.starlink.table.ValueInfo createCombinedInfo(uk.ac.starlink.table.ValueInfo info, Unit scaleUnit)
Returns a metadata object that describes the result of applying this combiner to data described by a given metadata object.- Parameters:
info
- metadata for values to be combined, usually numeric; may be null if metadata unknownscaleUnit
- unit of bin extent by which bin values are divided for density-like combiners; may be null for unknown/natural units- Returns:
- metadata for combined values; the content class must be be a primitive numeric wrapper class
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
getKnownCombiners
public static Combiner[] getKnownCombiners()
Returns a list of the known general purpose instances of this class.- Returns:
- combiner list
-
createDefaultBinList
public static BinList createDefaultBinList(Combiner combiner, long size)
Returns a BinList implementation suitable for a given number of bins and a given combiner. This may return an implementation based on a hash, or an array, or some combination.- Parameters:
combiner
- combinersize
- maximum number of bins
-
-