org.gicentre.utils.stat

## Class AbstractChart

- java.lang.Object
- - org.gicentre.utils.stat.AbstractChart

- Direct Known Subclasses:
    BarChart, XYChart

      public abstract class AbstractChart
      extends java.lang.Object

  Abstract class for representing a statistical chart. This class provides the core functionality common to all charts. A chart will contain a set of axes each corresponding to a set of data. The way in which each axis/data set is displayed will depend on the nature of the chart represented by the subclass.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `AbstractChart.Side` Indicates a side of the chart

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `axisColour` Colour of axis lines.
    `protected java.text.DecimalFormat[]` | `axisFormatter` For numerical formatting of axis labels.
    `protected int` | `axisLabelColour` Colour of axis labels.
    `protected int` | `axisValuesColour` Colour of the values shown on a chart axis.
    `protected float[][]` | `data` The datasets to be charted.
    `protected boolean` | `drawDecorations`
    `protected processing.core.PGraphics` | `graphics` Graphics context in which to send output.
    `protected float[][]` | `logTics` Tic mark values for optional axis display.
    `protected processing.core.PApplet` | `parent` Parent sketch in which this chart is to be drawn.
    `protected Drawable` | `renderer` Alternative renderer for sketchy graphics and other styles.
    `protected boolean` | `showEdge` Determines if areal chart features are drawn with an edge or not.
    `protected float[][]` | `tics` Tic mark values for optional axis display.
    `protected boolean` | `transposeAxes` Determines if the two primary axes should be transposed.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `AbstractChart(processing.core.PApplet parent)` Initialises the chart settings.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected static float` | `convertFromLog(double logValue, double minLogValue, double maxLogValue)` Converts the given value assumed to be on a log scale between 0 and 1, to an non-log value.
    `protected static float` | `convertToLog(double dataItem, double minLogValue, double maxLogValue)` Converts the given value, which is assumed to be positive, to a log value scaled between 0 and 1
    `protected abstract void` | `draw(float xOrigin, float yOrigin, float width, float height)` Should draw the chart within the given bounds.
    `protected float` | `getBorder(AbstractChart.Side side)` Reports the internal border between the given edge of the chart and the drawing area.
    `protected float[]` | `getData(int dimension)` Reports the data to be displayed along the given axis of the chart.
    `protected boolean` | `getIsLogScale(int dimension)` Reports whether or not the data in the given dimension are to be represented on the log10 scale.
    `protected float` | `getMax(int dimension)` Reports the maximum value of the data to be charted on the axis of the given dimension.
    `protected float` | `getMaxLog(int dimension)` Reports the maximum value of the log10 of the data to be charted on the axis of the given dimension.
    `protected float` | `getMin(int dimension)` Reports the minimum value of the data to be charted on the axis of the given dimension.
    `protected float` | `getMinBorder()` Reports the minimum internal border between the chart and the drawing area.
    `protected float` | `getMinLog(int dimension)` Reports the minimum value of the log10 of the data to be charted on the axis of the given dimension.
    `protected boolean` | `getShowAxis(int dimension)` Reports whether or not the axis representing the given dimension is drawn.
    `void` | `setAxisColour(int colour)` Determines the colour of the axis lines of the chart
    `void` | `setAxisLabelColour(int colour)` Determines the colour of the axis labels of the chart
    `void` | `setAxisValuesColour(int colour)` Determines the colour of the axis values of the chart
    `protected void` | `setBorder(float border, AbstractChart.Side side)` Sets the internal border between the given edge of the chart and the drawing area.
    `protected void` | `setData(int dimension, float[] data)` Sets the data to be displayed along the given axis of the chart.
    `void` | `setDecorations(boolean drawDecorations)` Determines whether decorations such as title, axes, and labels are drawn or not.
    `protected void` | `setFormat(int dimension, java.lang.String format)` Sets the numerical format for numbers shown on the axis of the given dimension.
    `void` | `setGraphics(processing.core.PGraphics graphics)` Sets the the graphics context into which all output is directed.
    `protected void` | `setIsLogScale(int dimension, boolean isLog)` Determines whether or not the data in the given dimension are to be represented on the log10 scale.
    `protected void` | `setMax(int dimension, float max)` Sets the maximum value of the data to be charted on the axis of the given dimension.
    `protected void` | `setMin(int dimension, float min)` Sets the minimum value of the data to be charted on the axis of the given dimension.
    `protected void` | `setMinBorder(float border)` Sets the minimum internal border between the edge of the graph and the drawing area.
    `protected void` | `setMinBorder(float border, AbstractChart.Side side)` Sets the minimum internal border between the given edge of the chart and the drawing area.
    `protected void` | `setRange(int dimension, float min, float max)` Sets the minimum and maximum values of the data to be charted on the axis of the given dimension.
    `void` | `setRenderer(Drawable renderer)` Sets the the renderer to be used for drawing graphics.
    `void` | `setShowEdge(boolean showEdge)` Determines whether or not to draw lines around and areal chart features.
    `protected void` | `showAxis(int dimension, boolean isVisible, AbstractChart.Side side)` Determines whether or not the axis representing the given dimension is drawn.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### parent

          protected processing.core.PApplet parent

      Parent sketch in which this chart is to be drawn.

    - #### graphics

          protected processing.core.PGraphics graphics

      Graphics context in which to send output.

    - #### renderer

          protected Drawable renderer

      Alternative renderer for sketchy graphics and other styles.

    - #### data

          protected float[][] data

      The datasets to be charted.

    - #### tics

          protected float[][] tics

      Tic mark values for optional axis display.

    - #### logTics

          protected float[][] logTics

      Tic mark values for optional axis display.

    - #### transposeAxes

          protected boolean transposeAxes

      Determines if the two primary axes should be transposed.

    - #### axisFormatter

          protected java.text.DecimalFormat[] axisFormatter

      For numerical formatting of axis labels.

    - #### axisColour

          protected int axisColour

      Colour of axis lines.

    - #### axisValuesColour

          protected int axisValuesColour

      Colour of the values shown on a chart axis.

    - #### axisLabelColour

          protected int axisLabelColour

      Colour of axis labels.

    - #### showEdge

          protected boolean showEdge

      Determines if areal chart features are drawn with an edge or not.

    - #### drawDecorations

          protected boolean drawDecorations

  - ### Constructor Detail

    - #### AbstractChart

          protected AbstractChart(processing.core.PApplet parent)

      Initialises the chart settings. Subclasses should normally call this constructor as a convenience to initialise properties common to all charts.
      Parameters:
        `parent` - Sketch in which this chart is to appear.

  - ### Method Detail

    - #### draw

          protected abstract void draw(float xOrigin,
                                       float yOrigin,
                                       float width,
                                       float height)

      Should draw the chart within the given bounds. All implementing classes must include this method do do the drawing.
      Parameters:
        `xOrigin` - left-hand pixel coordinate of the area in which to draw the chart.
        `yOrigin` - top pixel coordinate of the area in which to draw the chart.
        `width` - Width in pixels of the area in which to draw the chart.
        `height` - Height in pixels of the area in which to draw the chart.

    - #### setGraphics

          public void setGraphics(processing.core.PGraphics graphics)

      Sets the the graphics context into which all output is directed. This method allows output to be redirected to print output, offscreen buffers etc. Note that changing the graphics context in this way will also reset the renderer used to draw the graphics.
      Parameters:
        `graphics` - New graphics context in which the chart is embedded.

    - #### setRenderer

          public void setRenderer(Drawable renderer)

      Sets the the renderer to be used for drawing graphics. This allows alternative renderers to be substituted for fine-grain control of graphical appearance. Note that if the graphics context is changed with `setGraphics()`, any custom renderers will be lost.
      Parameters:
        `renderer` - New renderer to be used for drawing graphics.

    - #### setDecorations

          public void setDecorations(boolean drawDecorations)

      Determines whether decorations such as title, axes, and labels are drawn or not. This can be useful when two or more graphs with the same decorations are to be overlain. Only one of the graphs need draw the decorations.
      Parameters:
        `drawDecorations` - If true, axes, labels and titles can be drawn.

    - #### setAxisColour

          public void setAxisColour(int colour)

      Determines the colour of the axis lines of the chart
      Parameters:
        `colour` - Colour of the axis lines of the chart.

    - #### setAxisLabelColour

          public void setAxisLabelColour(int colour)

      Determines the colour of the axis labels of the chart
      Parameters:
        `colour` - Colour of the axis labels of the chart.

    - #### setAxisValuesColour

          public void setAxisValuesColour(int colour)

      Determines the colour of the axis values of the chart
      Parameters:
        `colour` - Colour of the axis values of the chart.

    - #### setShowEdge

          public void setShowEdge(boolean showEdge)

      Determines whether or not to draw lines around and areal chart features. If true the current stroke colour and weight will be used.
      Parameters:
        `showEdge` - Edges drawn if true.

    - #### setData

          protected void setData(int dimension,
                                 float[] data)

      Sets the data to be displayed along the given axis of the chart. Updates the min and max ranges in response to the new data.
      Parameters:
        `dimension` - Dimension of the data to add.
        `data` - Collection of data items to represent in the chart.

    - #### getData

          protected float[] getData(int dimension)

      Reports the data to be displayed along the given axis of the chart.
      Parameters:
        `dimension` - Dimension of the data to report.
      Returns:
        data Collection of data items represented in the chart or null if no data exist in the given dimension.

    - #### setRange

          protected void setRange(int dimension,
                                  float min,
                                  float max)

      Sets the minimum and maximum values of the data to be charted on the axis of the given dimension. If either the min or max values given are `Float.NaN`, then the minimum or maximum value respectively will be set to that of the min/max data items in the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose minimum value is to be set.
        `min` - Minimum value to be represented on the axis or `Float.NaN` for natural data minimum.
        `max` - Maximum value to be represented on the axis or `Float.NaN` for natural data maximum..

    - #### setMin

          protected void setMin(int dimension,
                                float min)

      Sets the minimum value of the data to be charted on the axis of the given dimension. If the given value is `Float.NaN`, then the minimum value will be set to the minimum of the data items in the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose minimum value is to be set.
        `min` - Minimum value to be represented on the axis or `Float.NaN` if data minimum is to be used.

    - #### getMin

          protected float getMin(int dimension)

      Reports the minimum value of the data to be charted on the axis of the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose minimum value is to be retrieved.
      Returns:
        Minimum value to be represented on the axis.

    - #### getMax

          protected float getMax(int dimension)

      Reports the maximum value of the data to be charted on the axis of the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose maximum value is to be retrieved.
      Returns:
        Maximum value to be represented on the axis.

    - #### getMinLog

          protected float getMinLog(int dimension)

      Reports the minimum value of the log10 of the data to be charted on the axis of the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose minimum value is to be retrieved.
      Returns:
        Minimum value to be represented on the axis assuming log scaling.

    - #### getMaxLog

          protected float getMaxLog(int dimension)

      Reports the maximum value of the log10 of the data to be charted on the axis of the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose maximum value is to be retrieved.
      Returns:
        Maximum value to be represented on the axis assuming log scaling.

    - #### setMax

          protected void setMax(int dimension,
                                float max)

      Sets the maximum value of the data to be charted on the axis of the given dimension. If the given value is `Float.NaN`, then the maximum value will be set to the maximum of the data items in the given dimension.
      Parameters:
        `dimension` - Dimension of the data whose maximum value is to be set.
        `max` - Maximum value to be represented on the axis or `Float.NaN` if data minimum is to be used.

    - #### setMinBorder

          protected void setMinBorder(float border)

      Sets the minimum internal border between the edge of the graph and the drawing area.
      Parameters:
        `border` - Minimum internal border size in pixel units.

    - #### setMinBorder

          protected void setMinBorder(float border,
                                      AbstractChart.Side side)

      Sets the minimum internal border between the given edge of the chart and the drawing area. If the given value is less than that given to the no-arguments method `setMinBorder()`, then this method has no effect.
      Parameters:
        `border` - Border at the given side in pixel units.
        `side` - Side of the chart to set the minimum border size.

    - #### setBorder

          protected void setBorder(float border,
                                   AbstractChart.Side side)

      Sets the internal border between the given edge of the chart and the drawing area. This method is used for explicit setting of border dimensions and will also reset the minimum border to the given dimension.
      Parameters:
        `border` - Border at the given side in pixel units.
        `side` - Side of the chart to set the border size.

    - #### getMinBorder

          protected float getMinBorder()

      Reports the minimum internal border between the chart and the drawing area.
      Returns:
        Minimum border between chart and drawing area in pixel units.

    - #### getBorder

          protected float getBorder(AbstractChart.Side side)

      Reports the internal border between the given edge of the chart and the drawing area. This value is at least `getMinBorder()` and large enough to accommodate any axis labelling.
      Parameters:
        `side` - Side of the chart to query.
      Returns:
        Border at the given side in pixel units.

    - #### showAxis

          protected void showAxis(int dimension,
                                  boolean isVisible,
                                  AbstractChart.Side side)

      Determines whether or not the axis representing the given dimension is drawn.
      Parameters:
        `dimension` - Dimension of the data to have axis displayed or hidden.
        `isVisible` - Axis is drawn if true.
        `side` - Side of chart along which axis is drawn.

    - #### getShowAxis

          protected boolean getShowAxis(int dimension)

      Reports whether or not the axis representing the given dimension is drawn.
      Parameters:
        `dimension` - Dimension of the data to query.
      Returns:
        True if given axis dimension is drawn.

    - #### getIsLogScale

          protected boolean getIsLogScale(int dimension)

      Reports whether or not the data in the given dimension are to be represented on the log10 scale.
      Parameters:
        `dimension` - Dimension of the data to query.
      Returns:
        True if the data in the given dimension are to be log-scaled.

    - #### setIsLogScale

          protected void setIsLogScale(int dimension,
                                       boolean isLog)

      Determines whether or not the data in the given dimension are to be represented on the log10 scale.
      Parameters:
        `dimension` - Dimension of the data to set.
        `isLog` - True if the data in the given dimension are to be log-scaled or false if linear.

    - #### setFormat

          protected void setFormat(int dimension,
                                   java.lang.String format)

      Sets the numerical format for numbers shown on the axis of the given dimension.
      Parameters:
        `dimension` - Dimension of the data axis to format.
        `format` - Format for numbers on the given data axis.

    - #### convertToLog

          protected static float convertToLog(double dataItem,
                                              double minLogValue,
                                              double maxLogValue)

      Converts the given value, which is assumed to be positive, to a log value scaled between 0 and 1
      Parameters:
        `dataItem` - Item from which to find log value.
        `minLogValue` - Minimum value of the log10 of dataItem (used to scale result between 0-1)
        `maxLogValue` - Maximum value of the log10 of dataItem (used to scale result between 0-1)
      Returns:
        Log-scaled equivalent of the given value.

    - #### convertFromLog

          protected static float convertFromLog(double logValue,
                                                double minLogValue,
                                                double maxLogValue)

      Converts the given value assumed to be on a log scale between 0 and 1, to an non-log value.
      Parameters:
        `logValue` - 0-1 log value from which the data value is to be found. If this value is outside the 0-1 range, a value of 0 will be returned.
        `minLogValue` - Minimum value of the log10 of dataItem (used to unscale the logValue from 0-1)
        `maxLogValue` - Maximum value of the log10 of dataItem (used to unscale the logValue from 0-1)
      Returns:
        Data value that would have produced the given scaled log value within the given range.