# Class Normalisation

java.lang.Object
uk.ac.starlink.ttools.plot2.layer.Normalisation

@Equality public abstract class Normalisation extends Object
Defines normalisation modes for histogram-like plots.

Since:
  19 Feb 2015
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`static final Normalisation`
`AREA`
The total area of histogram bars is normalised to unity.
`static final Normalisation`
`HEIGHT`
The total height of histogram bars is normalised to unity.
`static final Normalisation`
`MAXIMUM`
Height of the tallest histogram bar is normalised to unity.
`static final Normalisation`
`NONE`
No normalisation is performed.
`static final Normalisation`
`UNIT`
Bars scaled by inverse bin width.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`Normalisation(String name, String description)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`String`
`getDescription()`
Returns a short description of this mode.
`static Normalisation[]`
`getKnownValues()`
Returns the Normalisation instances defined by this class.
`abstract double`
`getScaleFactor(double sum, double max, double binWidth, Combiner.Type ctype, boolean isCumulative)`
Returns the value by which all bins should be scaled to achieve normalisation for a given data set.
`String`
`toString()`

### Methods inherited from class Object

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

## Field Details

### NONE

public static final Normalisation NONE
No normalisation is performed.

### AREA

public static final Normalisation AREA
The total area of histogram bars is normalised to unity.

### UNIT

public static final Normalisation UNIT
Bars scaled by inverse bin width.

### MAXIMUM

public static final Normalisation MAXIMUM
Height of the tallest histogram bar is normalised to unity.

### HEIGHT

public static final Normalisation HEIGHT
The total height of histogram bars is normalised to unity.

## Constructor Details

### Normalisation

protected Normalisation(String name, String description)
Constructor.

Parameters:
  `name` - mode name
  `description` - short description

## Method Details

### getDescription

public String getDescription()
Returns a short description of this mode.

Returns:
  description

### getScaleFactor

public abstract double getScaleFactor(double sum, double max, double binWidth, Combiner.Type ctype, boolean isCumulative)
Returns the value by which all bins should be scaled to achieve normalisation for a given data set.

The `binWidth` should at least make sense in terms of screen area. For linear X axis, it should be in data units, but for logarithmic X axis it may have to be in log(data units). The `binWidth` is only used by AREA and UNIT modes.

For cumulative plots, all the modes except NONE behave the same, normalising the total value to unity. The Combiner.Type may result in scaling the values by the inverse of the bin width. However, that is sometimes done anyway (UNIT and AREA modes), so for those cases it's ignored, since you don't want to apply that correction twice.

Parameters:
  `sum` - total height of all histogram bars
  `max` - height of tallest histogram bar
  `binWidth` - constant linear width of histogram bars, or NaN
  `ctype` - combiner type used to populate bins
  `isCumulative` - true iff the plot is cumulative

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### getKnownValues

public static Normalisation[] getKnownValues()
Returns the Normalisation instances defined by this class.

Returns:
  list of normalisation instances