org.gicentre.utils.stat

## Class XYChart

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

-     public class XYChart
      extends AbstractChart

  Class for representing X-Y charts such as scatterplots or line charts.
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.gicentre.utils.stat.AbstractChart

      `AbstractChart.Side`

  - ### Field Summary

    - ### Fields inherited from class org.gicentre.utils.stat.AbstractChart

      `axisColour, axisFormatter, axisLabelColour, axisValuesColour, data, drawDecorations, graphics, logTics, parent, renderer, showEdge, tics, transposeAxes`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XYChart(processing.core.PApplet parent)` Initialises an XY chart.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `calcDataSpacing()` Calculates the spacing between the graph area and the data to display.
    `void` | `draw(float xOrigin, float yOrigin, float width, float height)` Draws the X-Y chart within the given bounds.
    `float` | `getBottomSpacing()` Reports the spacing between the bottom of the chart and the bottom of the dataspace within the chart.
    `processing.core.PVector` | `getDataToScreen(processing.core.PVector dataPoint)` Converts given data point into its screen location.
    `float` | `getLeftSpacing()` Reports the spacing between the left of the chart and the left of the dataspace within the chart.
    `float` | `getMaxX()` Reports the maximum x value that can be displayed by the XY chart.
    `float` | `getMaxY()` Reports the maximum y value that can be displayed by the XY chart.
    `float` | `getMinX()` Reports the minimum x value that can be displayed by the XY chart.
    `float` | `getMinY()` Reports the minimum y value that can be displayed by the XY chart.
    `float` | `getRightSpacing()` Reports the spacing between the right of the chart and the right of the dataspace within the chart.
    `processing.core.PVector` | `getScreenToData(processing.core.PVector screenPoint)` Converts given screen coordinate into its equivalent data value.
    `float` | `getTopSpacing()` Reports the spacing between the top of the chart and the top of the dataspace within the chart.
    `float[]` | `getXData()` Reports the data values that are displayed in the chart along the X axis.
    `float[]` | `getYData()` Reports the data values that are displayed in the chart along the Y axis.
    `void` | `setData(float[] xValues, float[] yValues)` Sets the data to be plotted in the X-Y chart.
    `void` | `setData(java.util.List<processing.core.PVector> data)` Sets the data to be plotted in the X-Y chart
    `void` | `setLineColour(int colour)` Determines the colour of the line to be displayed on the chart.
    `void` | `setLineWidth(float width)` Determines the width of the line to be displayed on the chart.
    `void` | `setLogX(boolean isLog)` Determines whether or not the values on the x axis are log10 scaled.
    `void` | `setLogY(boolean isLog)` Determines whether or not the values on the y axis are log10 scaled.
    `void` | `setMaxX(float maxX)` Sets the maximum value for x values to be represented.
    `void` | `setMaxY(float maxY)` Sets the maximum value for y values to be represented.
    `void` | `setMinX(float minX)` Sets the minimum value for x values to be represented.
    `void` | `setMinY(float minY)` Sets the minimum value for y values to be represented.
    `void` | `setPointColour(float[] colourData, ColourTable cTable)` Provides the data and colour table from which to colour points.
    `void` | `setPointColour(int colour)` Determines the colour of the points to be displayed on the chart.
    `void` | `setPointSize(float size)` Determines the size of the points to be displayed on the chart.
    `void` | `setPointSize(float[] sizeData, float maxSize)` Sizes points to be displayed on the chart according to the given set of data.
    `void` | `setXAxisAt(float yValue)` Sets the position of the x-axis.
    `void` | `setXAxisLabel(java.lang.String label)` Sets the x-axis label.
    `void` | `setXFormat(java.lang.String format)` Sets the numerical format for numbers shown on the x-axis.
    `void` | `setYAxisAt(float xValue)` Sets the position of the y-axis.
    `void` | `setYAxisLabel(java.lang.String label)` Sets the y-axis label.
    `void` | `setYFormat(java.lang.String format)` Sets the numerical format for numbers shown on the y-axis.
    `void` | `showXAxis(boolean showAxis)` Determines whether or not the axis representing the x data is shown.
    `void` | `showYAxis(boolean showAxis)` Determines whether or not the axis representing the y data is shown.
    `void` | `transposeAxes(boolean transpose)` Determines if the axes should be transposed (so that the x-axis is vertical and y-axis is horizontal).
    `void` | `updateLayout()` Updates the layout of the chart if, for example the font has been changed externally.

    - ### Methods inherited from class org.gicentre.utils.stat.AbstractChart

      `convertFromLog, convertToLog, getBorder, getData, getIsLogScale, getMax, getMaxLog, getMin, getMinBorder, getMinLog, getShowAxis, setAxisColour, setAxisLabelColour, setAxisValuesColour, setBorder, setData, setDecorations, setFormat, setGraphics, setIsLogScale, setMax, setMin, setMinBorder, setMinBorder, setRange, setRenderer, setShowEdge, showAxis`

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

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

- - ### Constructor Detail

    - #### XYChart

          public XYChart(processing.core.PApplet parent)

      Initialises an XY chart.
      Parameters:
        `parent` - Parent sketch in which this chart is to be drawn.

  - ### Method Detail

    - #### setData

          public void setData(float[] xValues,
                              float[] yValues)

      Sets the data to be plotted in the X-Y chart. The arrays of x and y values supplied must be the same length for this method to have any effect.
      Parameters:
        `xValues` - Array of x values to plot.
        `yValues` - Array of y values to plot.

    - #### setData

          public void setData(java.util.List<processing.core.PVector> data)

      Sets the data to be plotted in the X-Y chart
      Parameters:
        `data` - Collection of pairs of (x,y) data values, each stored in a PVector.

    - #### draw

          public void draw(float xOrigin,
                           float yOrigin,
                           float width,
                           float height)

      Draws the X-Y chart within the given bounds.
      Specified by:
        `draw` in class `AbstractChart`
      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.

    - #### getDataToScreen

          public processing.core.PVector getDataToScreen(processing.core.PVector dataPoint)

      Converts given data point into its screen location. This location will be based on the last time the data were drawn with the `draw()` method. If this is called before any call to `draw()` has been made, it will return null.
      Parameters:
        `dataPoint` - (x,y) pair representing an item of data.
      Returns:
        Screen coordinates corresponding to the given data point or null if screen space undefined.

    - #### getScreenToData

          public processing.core.PVector getScreenToData(processing.core.PVector screenPoint)

      Converts given screen coordinate into its equivalent data value. This value will be based on the last time the data were drawn with the `draw()` method. If this is called before any call to `draw()` has been made, it will return null.
      Parameters:
        `screenPoint` - Screen coordinates to convert into data pair.
      Returns:
        (x,y) pair representing an item of data that would be displayed at the given screen location or null if screen space not defined or screenPoint is outside of the visible chart space.

    - #### setPointColour

          public void setPointColour(int colour)

      Determines the colour of the points to be displayed on the chart. This method will give a uniform colour to all points.
      Parameters:
        `colour` - Colour of points to be displayed.

    - #### setPointColour

          public void setPointColour(float[] colourData,
                                     ColourTable cTable)

      Provides the data and colour table from which to colour points. Each data item should by in the same order as the data provided to `setData()`.
      Parameters:
        `colourData` - Data used to colour points.
        `cTable` - Colour table that translates data values into colours.

    - #### setLineColour

          public void setLineColour(int colour)

      Determines the colour of the line to be displayed on the chart.
      Parameters:
        `colour` - Colour of line to be displayed.

    - #### setPointSize

          public void setPointSize(float size)

      Determines the size of the points to be displayed on the chart. This method will give a uniform size to all points. If set to 0 or less, no points are drawn.
      Parameters:
        `size` - Size of points to be displayed in pixel units.

    - #### setPointSize

          public void setPointSize(float[] sizeData,
                                   float maxSize)

      Sizes points to be displayed on the chart according to the given set of data. Each data item should by in the same order as the data provided to `setData()`.
      Parameters:
        `sizeData` - Data used to size points.
        `maxSize` - Size in pixel units of the largest point.

    - #### setLineWidth

          public void setLineWidth(float width)

      Determines the width of the line to be displayed on the chart. If set to 0 or less, no line is drawn.
      Parameters:
        `width` - Width of line to be displayed in pixel units.

    - #### showXAxis

          public void showXAxis(boolean showAxis)

      Determines whether or not the axis representing the x data is shown.
      Parameters:
        `showAxis` - x-axis is shown if true.

    - #### showYAxis

          public void showYAxis(boolean showAxis)

      Determines whether or not the axis representing the y data is shown.
      Parameters:
        `showAxis` - y-axis is shown if true.

    - #### setMinX

          public void setMinX(float minX)

      Sets the minimum value for x values to be represented. This can be used to force the x-axis to start at 0 or some other value. If the given value is `Float.NaN`, then the minimum x-value will be set to the minimum of the data x-values in the chart.
      Parameters:
        `minX` - Minimum x-value to be represented on the x-axis.

    - #### setMinY

          public void setMinY(float minY)

      Sets the minimum value for y values to be represented. This can be used to force the y-axis to start at 0 or some other value. If the given value is `Float.NaN`, then the minimum y-value will be set to the minimum of the data y-values in the chart.
      Parameters:
        `minY` - Minimum y-value to be represented on the y-axis.

    - #### setMaxX

          public void setMaxX(float maxX)

      Sets the maximum value for x values to be represented. This can be used to force multiple charts to share the same axis range independently of data to be represented. If the given value is `Float.NaN`, then the maximum x-value will be set to the maximum of the data x-values in the chart.
      Parameters:
        `maxX` - Maximum x-value to be represented on the x-axis or `Float.NaN` to use data maximum.

    - #### setMaxY

          public void setMaxY(float maxY)

      Sets the maximum value for y values to be represented. This can be used to force multiple charts to share the same axis range independently of data to be represented. If the given value is `Float.NaN`, then the minimum y-value will be set to the maximum of the data y-values in the chart.
      Parameters:
        `maxY` - Maximum y-value to be represented on the y-axis or `Float.NaN` go use the data maximum.

    - #### getXData

          public float[] getXData()

      Reports the data values that are displayed in the chart along the X axis.
      Returns:
        Sequence of data values represented by their position along the x-axis.

    - #### getYData

          public float[] getYData()

      Reports the data values that are displayed in the chart along the Y axis.
      Returns:
        Sequence of data values represented by their position along the y-axis.

    - #### getMinX

          public float getMinX()

      Reports the minimum x value that can be displayed by the XY chart. Note that this need not necessarily be the same as the minimum data value being displayed since axis rounding or calls to `setMinX()` can affect the value.
      Returns:
        Minimum value that can be represented by the XY chart on the x axis.

    - #### getMaxX

          public float getMaxX()

      Reports the maximum x value that can be displayed by the XY chart. Note that this need not necessarily be the same as the maximum data value being displayed since axis rounding or calls to `setMaxX()` can affect the value.
      Returns:
        Maximum value that can be represented by the XY chart on the x axis.

    - #### getMinY

          public float getMinY()

      Reports the minimum y value that can be displayed by the XY chart. Note that this need not necessarily be the same as the minimum data value being displayed since axis rounding or calls to `setMinY()` can affect the value.
      Returns:
        Minimum value that can be represented by the XY chart on the y axis.

    - #### getMaxY

          public float getMaxY()

      Reports the maximum y value that can be displayed by the XY chart. Note that this need not necessarily be the same as the maximum data value being displayed since axis rounding or calls to `setMaxY()` can affect the value.
      Returns:
        Maximum value that can be represented by the XY chart on the y axis.

    - #### getLeftSpacing

          public float getLeftSpacing()

      Reports the spacing between the left of the chart and the left of the dataspace within the chart. This value is the space required for drawing the axis and labels.
      Returns:
        Spacing between dataspace and graph bounds.

    - #### getRightSpacing

          public float getRightSpacing()

      Reports the spacing between the right of the chart and the right of the dataspace within the chart.
      Returns:
        Spacing between dataspace and graph bounds.

    - #### getBottomSpacing

          public float getBottomSpacing()

      Reports the spacing between the bottom of the chart and the bottom of the dataspace within the chart. This value is the space required for drawing the axis and labels.
      Returns:
        Spacing between dataspace and graph bounds.

    - #### getTopSpacing

          public float getTopSpacing()

      Reports the spacing between the top of the chart and the top of the dataspace within the chart.
      Returns:
        Spacing between dataspace and graph bounds.

    - #### setXAxisLabel

          public void setXAxisLabel(java.lang.String label)

      Sets the x-axis label. If null, no label is drawn.
      Parameters:
        `label` - x-axis label to draw or null if no label to be drawn.

    - #### setYAxisLabel

          public void setYAxisLabel(java.lang.String label)

      Sets the y-axis label. If null, no label is drawn.
      Parameters:
        `label` - y-axis label to draw or null if no label to be drawn.

    - #### setXAxisAt

          public void setXAxisAt(float yValue)

      Sets the position of the x-axis. Note that this position will be somewhere on along the y-range.
      Parameters:
        `yValue` - Position of axis in data units.

    - #### setYAxisAt

          public void setYAxisAt(float xValue)

      Sets the position of the y-axis. Note that this position will be somewhere on along the x-range.
      Parameters:
        `xValue` - Position of axis in data units.

    - #### setXFormat

          public void setXFormat(java.lang.String format)

      Sets the numerical format for numbers shown on the x-axis.
      Parameters:
        `format` - Format for numbers on the x-axis.

    - #### setYFormat

          public void setYFormat(java.lang.String format)

      Sets the numerical format for numbers shown on the y-axis.
      Parameters:
        `format` - Format for numbers on the y-axis.

    - #### setLogX

          public void setLogX(boolean isLog)

      Determines whether or not the values on the x axis are log10 scaled.
      Parameters:
        `isLog` - True if x-axis values are to be log10-scaled or false if linear.

    - #### setLogY

          public void setLogY(boolean isLog)

      Determines whether or not the values on the y axis are log10 scaled.
      Parameters:
        `isLog` - True if y-axis values are to be log10-scaled or false if linear.

    - #### transposeAxes

          public void transposeAxes(boolean transpose)

      Determines if the axes should be transposed (so that the x-axis is vertical and y-axis is horizontal).
      Parameters:
        `transpose` - Axes are transposed if true.

    - #### updateLayout

          public void updateLayout()

      Updates the layout of the chart if, for example the font has been changed externally.

    - #### calcDataSpacing

          public void calcDataSpacing()

      Calculates the spacing between the graph area and the data to display. This method need only be called if data spacing values are required and some aspect of the chart's spacing has changed since it was first constructed (e.g. axes have been shown).