# Class Pixel1dPlotter<S extends Style>

java.lang.Object
uk.ac.starlink.ttools.plot2.layer.Pixel1dPlotter<S>

All Implemented Interfaces:
  `Plotter<S>`

Direct Known Subclasses:
  `AbstractKernelDensityPlotter, DensogramPlotter`

public abstract class Pixel1dPlotter<S extends Style> extends Object implements Plotter<S>
Abstract superclass for histogram-like plotters that have pixel-sized bins with optional smoothing. Only works with PlanarSurfaces.

Since:
  20 Feb 2015
Author:
  Mark Taylor

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`Pixel1dPlotter.BinArray`
Data object storing counts per pixel.
`static class`
`Pixel1dPlotter.Pixel1dPlan`
Plot plan implementation for this class.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final ConfigKey<Kernel1dShape>`
`KERNEL_KEY`
Config key for smoothing kernel shape.
`static final ConfigKey<BinSizer>`
`SMOOTHSIZER_KEY`
Config key for smoothing width configuration.
`static final ReportKey<Double>`
`SMOOTHWIDTH_KEY`
Report key for smoothing width.

## Constructor Summary

Constructors
Modifier
Constructor
Description
`protected`
`Pixel1dPlotter(FloatingCoord xCoord, boolean hasWeight, ConfigKey<Unit> unitKey, String name, Icon icon)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static Kernel1d`
`createKernel(Kernel1dShape kernelShape, BinSizer sizer, Axis xAxis, boolean xLog, boolean isMean)`
Creates a new kernel from configuration items.
`PlotLayer`
`createLayer(DataGeom geom, DataSpec dataSpec, S style)`
The supplied `geom` is ignored.
`protected abstract void`
`extendPixel1dCoordinateRanges(Range[] ranges, boolean[] logFlags, S style, DataSpec dataSpec, DataStore dataStore)`
Performs any required range extension.
`protected abstract Combiner`
`getCombiner(S style)`
Returns the bin aggregation mode implied by a given style.
`ConfigKey<Combiner>`
`getCombinerKey()`
Returns the combination mode configuration key for this plotter.
`CoordGroup`
`getCoordGroup()`
Returns an object describing which data coordinates are used for this plotter and how they are arranged in supplied DataSpec objects.
`static double[]`
`getDataBins(Pixel1dPlotter.BinArray binArray, Axis xAxis, Kernel1d kernel, Normalisation norm, Combiner.Type ctype, Unit unit, Cumulation cumul)`
Returns an array of data coordinate values, one for each bin accumulated by the bin array (X pixel value).
`static int`
`getEffectiveExtent(Kernel1d kernel)`
Returns the range of a given kernel over which it will be evaluated for the purposes of this plotter.
`protected abstract LayerOpt`
`getLayerOpt(S style)`
Returns the LayerOpt suitable for a given style for this plotter.
`protected abstract ReportMap`
`getPixel1dReport(Pixel1dPlotter.Pixel1dPlan plan, S style, boolean xLog)`
Returns information associated with the plot.
`protected abstract int`
`getPixelPadding(S style, PlanarSurface surf)`
Returns the padding required at both ends of the array of pixel bins for calculations.
`static double`
`getPixelWidth(BinSizer sizer, Axis xAxis, boolean xLog)`
Calculates the width in pixel coordinates represented by a bin sizer applied to a given axis.
`Icon`
`getPlotterIcon()`
Returns an icon for this plotter for use in user interface.
`String`
`getPlotterName()`
Returns the name of this plotter for use in user interface.
`int`
`getWeightCoordIndex()`
Returns the DataSpec coord index used for the weighting data for this plotter.
`protected String`
`getWeightingDescription()`
Returns an XML description snippet (zero or more P elements) discussing use of weighted coordinates for this plotter.
`boolean`
`hasReports()`
Indicates whether the drawings produced by this plotter will return general interest report information to upstream plotting code.
`protected abstract boolean`
`isY(S style)`
Returns the sideways flag implied by a given style.
`protected abstract void`
`paintBins(PlanarSurface surface, Pixel1dPlotter.BinArray binArray, S style, Graphics2D g)`
Draws the graphical representation of a given array of counts per horizontal pixel.
`Pixel1dPlotter.BinArray`
`readBins(Axis xAxis, int padPix, Combiner combiner, DataSpec dataSpec, DataStore dataStore)`
Reads per-horizontal-pixel frequency data from a given data set.

### Methods inherited from class Object

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

### Methods inherited from interface Plotter

`createStyle, getPlotterDescription, getRangeStyleKey, getStyleKeys`

## Field Details

### SMOOTHWIDTH_KEY

public static final ReportKey<Double> SMOOTHWIDTH_KEY
Report key for smoothing width.

### SMOOTHSIZER_KEY

public static final ConfigKey<BinSizer> SMOOTHSIZER_KEY
Config key for smoothing width configuration.

### KERNEL_KEY

public static final ConfigKey<Kernel1dShape> KERNEL_KEY
Config key for smoothing kernel shape.

## Constructor Details

### Pixel1dPlotter

protected Pixel1dPlotter(FloatingCoord xCoord, boolean hasWeight, ConfigKey<Unit> unitKey, String name, Icon icon)
Constructor.

Parameters:
  `xCoord` - X axis coordinate
  `hasWeight` - true to permit histogram weighting
  `unitKey` - config key to select X axis physical units, or null if no unit selection required
  `name` - plotter name
  `icon` - plotter icon

## Method Details

### getPlotterName

public String getPlotterName()
Description copied from interface: `Plotter`
Returns the name of this plotter for use in user interface.

Specified by:
  `getPlotterName` in interface `Plotter<S extends Style>`
Returns:
  user-directed plotter name

### getPlotterIcon

public Icon getPlotterIcon()
Description copied from interface: `Plotter`
Returns an icon for this plotter for use in user interface.

Specified by:
  `getPlotterIcon` in interface `Plotter<S extends Style>`
Returns:
  plotter icon

### getCoordGroup

public CoordGroup getCoordGroup()
Description copied from interface: `Plotter`
Returns an object describing which data coordinates are used for this plotter and how they are arranged in supplied DataSpec objects.

Specified by:
  `getCoordGroup` in interface `Plotter<S extends Style>`
Returns:
  coordinate group

### hasReports

public boolean hasReports()
Description copied from interface: `Plotter`
Indicates whether the drawings produced by this plotter will return general interest report information to upstream plotting code.

Specified by:
  `hasReports` in interface `Plotter<S extends Style>`
Returns:
  true if the plot report may return interesting information
See Also:
  - `Drawing.getReport(Object)`

### getWeightingDescription

protected String getWeightingDescription()
Returns an XML description snippet (zero or more P elements) discussing use of weighted coordinates for this plotter.

Returns:
  text suitable for inclusion in getPlotterDescription return value

### isY

protected abstract boolean isY(S style)
Returns the sideways flag implied by a given style.

Parameters:
  `style` - plot style
Returns:
  if true, plot is sideways

### getLayerOpt

protected abstract LayerOpt getLayerOpt(S style)
Returns the LayerOpt suitable for a given style for this plotter.

Parameters:
  `style` - plot style
Returns:
  layer option flags

### getPixelPadding

protected abstract int getPixelPadding(S style, PlanarSurface surf)
Returns the padding required at both ends of the array of pixel bins for calculations.

Parameters:
  `style` - plotting style
  `surf` - plotting surface
Returns:
  padding in pixels required in bin array

### getCombiner

protected abstract Combiner getCombiner(S style)
Returns the bin aggregation mode implied by a given style.

Parameters:
  `style` - plotting style
Returns:
  pixel bin aggregation mode

### paintBins

protected abstract void paintBins(PlanarSurface surface, Pixel1dPlotter.BinArray binArray, S style, Graphics2D g)
Draws the graphical representation of a given array of counts per horizontal pixel.

Parameters:
  `surface` - plotting surface
  `binArray` - counts per X axis pixel
  `style` - plotting style
  `g` - graphics context

### extendPixel1dCoordinateRanges

protected abstract void extendPixel1dCoordinateRanges(Range[] ranges, boolean[] logFlags, S style, DataSpec dataSpec, DataStore dataStore)
Performs any required range extension. May be a no-op.

Parameters:
  `ranges` - array of data space dimension ranges to update
  `logFlags` - array of linear/log flags corresponding to ranges
  `style` - plotting style
  `dataSpec` - data specification
  `dataStore` - data storage object
See Also:
  - `PlotLayer.extendCoordinateRanges(Range[], boolean[], DataStore)`

### getPixel1dReport

protected abstract ReportMap getPixel1dReport(Pixel1dPlotter.Pixel1dPlan plan, S style, boolean xLog)
Returns information associated with the plot.

Parameters:
  `plan` - plotting plan
  `style` - plot style
  `xLog` - true iff X axis is logarithmic
Returns:
  report info, may be null
See Also:
  - `Drawing.getReport(Object)`

### getCombinerKey

public ConfigKey<Combiner> getCombinerKey()
Returns the combination mode configuration key for this plotter.

Returns:
  combiner key

### createLayer

public PlotLayer createLayer(DataGeom geom, DataSpec dataSpec, S style)
The supplied `geom` is ignored.

Specified by:
  `createLayer` in interface `Plotter<S extends Style>`
Parameters:
  `geom` - indicates base position coordinates and their mapping to points in the data space
  `dataSpec` - specifies the data required for the plot
  `style` - data style as obtained from `createStyle`
Returns:
  new plot layer, or null if no drawing will take place

### getWeightCoordIndex

public int getWeightCoordIndex()
Returns the DataSpec coord index used for the weighting data for this plotter. If weighting is not supported, a negative value is returned.

Returns:
  weight coord index, or -1

### readBins

public Pixel1dPlotter.BinArray readBins(Axis xAxis, int padPix, Combiner combiner, DataSpec dataSpec, DataStore dataStore)
Reads per-horizontal-pixel frequency data from a given data set.

Parameters:
  `xAxis` - axis along which frequencies are accumulated
  `padPix` - number of pixels in each direction outside of the axis range over which counts should be gathered
  `combiner` - bin aggregation mode
  `dataSpec` - specification for frequency data values
  `dataStore` - data storage

### getDataBins

public static double[] getDataBins(Pixel1dPlotter.BinArray binArray, Axis xAxis, Kernel1d kernel, Normalisation norm, Combiner.Type ctype, Unit unit, Cumulation cumul)
Returns an array of data coordinate values, one for each bin accumulated by the bin array (X pixel value). This is basically the bin array results, but perhaps adjusted by style elements like smoothing, cumulativeness etc.

Parameters:
  `binArray` - basic results
  `xAxis` - axis over which counts are accumulated
  `kernel` - smoothing kernel
  `norm` - normalisation mode
  `ctype` - combiner type used to populate bins
  `unit` - unit for scaling X axis bin width
  `cumul` - cumulative representation
Returns:
  output data bin values

### getEffectiveExtent

public static int getEffectiveExtent(Kernel1d kernel)
Returns the range of a given kernel over which it will be evaluated for the purposes of this plotter. This is basically the kernel's extent, but it may be limited to some maximum for practical purposes.

Parameters:
  `kernel` - smoothing kernel
Returns:
  effective extent

### createKernel

public static Kernel1d createKernel(Kernel1dShape kernelShape, BinSizer sizer, Axis xAxis, boolean xLog, boolean isMean)
Creates a new kernel from configuration items.

Parameters:
  `kernelShape` - functional form
  `sizer` - determines width in data coordinates
  `xAxis` - axis on which samples occur
  `xLog` - true for logarithmic x axis, false for linear
  `isMean` - true if the smoothing is to suitable for intensive quantities like the mean, false for extensive quantities like a sum
Returns:
  kernel

### getPixelWidth

public static double getPixelWidth(BinSizer sizer, Axis xAxis, boolean xLog)
Calculates the width in pixel coordinates represented by a bin sizer applied to a given axis.

Parameters:
  `sizer` - determines width in data coordinates
  `xAxis` - axis on which samples occur
  `xLog` - true for logarithmic x axis, false for linear
Returns:
  width in pixel data coordinates represented by sizer, never negative