Combiner (Starlink-UK API)

java.lang.Object
- uk.ac.starlink.ttools.plot2.layer.Combiner

Direct Known Subclasses:

QuantileCombiner
```
@Equality
public abstract class Combiner
extends Object
```
Defines the combination mode for accumulating values into a bin.
Instances of this class can produce Container and BinList 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 calling Combiner.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 (like MEAN).

Since:

20 Sep 2015

Author:

Mark Taylor

Nested Class Summary

Nested Classes
Modifier and Type	Class and 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 and 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`	`POP_STDEV` Calculate the population standard deviation of all submitted values.
`static Combiner`	`Q01` Calculate the 1st percentile of all submitted values (slow).
`static Combiner`	`Q1` Calculate the first quartile of all submitted values (slow).
`static Combiner`	`Q3` Calculate the third quartile of all submitted values (slow).
`static Combiner`	`Q99` Calculate the 99th percentile of all submitted values (slow).
`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 and Description

protected Combiner(String name, String description, Combiner.Type type, boolean hasBigBin)
Constructor.

Constructors
Modifier	Constructor and Description
`protected`	`Combiner(String name, String description, Combiner.Type type, boolean hasBigBin)` Constructor.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`abstract ArrayBinList`	`createArrayBinList(int size)` May be able to create a bin list suitable for non-sparse, moderate-sized index ranges.
`abstract ValueInfo`	`createCombinedInfo(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 Combiner`	`createQuantileCombiner(String name, String descrip, double quantile)` Creates a combiner that calculates a given quantile.
`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.
`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.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 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).
  - Q1
```
public static final Combiner Q1
```
    Calculate the first quartile of all submitted values (slow).
  - Q3
```
public static final Combiner Q3
```
    Calculate the third quartile of all submitted values (slow).
  - SAMPLE_STDEV
```
public static final Combiner SAMPLE_STDEV
```
    Calculate the sample standard deviation of all submitted values.
  - POP_STDEV
```
public static final Combiner POP_STDEV
```
    Calculate the population 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.
  - Q01
```
public static final Combiner Q01
```
    Calculate the 1st percentile of all submitted values (slow).
  - Q99
```
public static final Combiner Q99
```
    Calculate the 99th percentile of all submitted values (slow).
- Constructor Detail
  - Combiner
```
protected Combiner(String name,
                   String description,
                   Combiner.Type type,
                   boolean hasBigBin)
```
    Constructor.
    
    Parameters:
    
    name - name
    
    description - short textual description
    
    type - 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 results
    
    hasBigBin - indicates whether the bins used by this combiner are large (take more memory than a double)
- 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 String getName()
```
    Returns this combiner's name.
    
    Returns:
    
    name
  - getDescription
```
public 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 a double. This flag may be used to decide whether to compact bin list results.
    
    Returns:
    
    true if this combiner uses big bins
  - createCombinedInfo
```
public abstract ValueInfo createCombinedInfo(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 unknown
    
    scaleUnit - 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 String toString()
```
    Overrides:
    
    toString in class Object
  - getKnownCombiners
```
public static Combiner[] getKnownCombiners()
```
    Returns a list of the known general purpose instances of this class.
    
    Returns:
    
    combiner list
  - createQuantileCombiner
```
public static Combiner createQuantileCombiner(String name,
                                              String descrip,
                                              double quantile)
```
    Creates a combiner that calculates a given quantile.
    
    Parameters:
    
    name - combiner name
    
    descrip - minimal description, or null
    
    quantile - quantile point, between 0 and 1
    
    Returns:
    
    combiner

Class Combiner

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

COUNT

DENSITY

SUM

WEIGHTED_DENSITY

MEAN

MEDIAN

Q1

Q3

SAMPLE_STDEV

POP_STDEV

MIN

MAX

HIT

Q01

Q99

Constructor Detail

Combiner

Method Detail

createContainer

createArrayBinList

getName

getDescription

getType

hasBigBin

createCombinedInfo

toString

getKnownCombiners

createQuantileCombiner