Package uk.ac.starlink.ttools.plot2.layer

Class 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 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 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 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 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 Combiner createQuantileCombiner​(java.lang.String name, java.lang.String descrip, double quantile)
      Creates a combiner that calculates a given quantile.
      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()  

      • 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.

      • 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​(java.lang.String name,
                   java.lang.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 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 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 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 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 java.lang.String toString()
        Overrides:
        toString in class java.lang.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​(java.lang.String name,
                                              java.lang.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