org.gicentre.utils.stat

## Class BarChart

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

-     public class BarChart
      extends AbstractChart

  Represents a bar chart. Appearance can be customised such as display of axes, bar colours, orientations etc.
  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
    `BarChart(processing.core.PApplet parent)` Initialises a bar chart.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `draw(float xOrigin, float yOrigin, float width, float height)` Draws the bar chart within the given bounds.
    `float[]` | `getData()` Reports the data values used to calculate bar lengths in the chart.
    `processing.core.PVector` | `getDataToScreen(processing.core.PVector dataPoint)` Converts given data point into its screen location.
    `float` | `getMaxValue()` Reports the maximum value that can be displayed by the bar chart.
    `float` | `getMinValue()` Reports the minimum value that can be displayed by the bar chart.
    `int` | `getNumBars()` Reports the number of bars in the bar chart.
    `processing.core.PVector` | `getScreenToData(processing.core.PVector screenPoint)` Converts given screen coordinate into its equivalent data value.
    `void` | `setBarColour(float[] colourData, ColourTable cTable)` Provides the data and colour table from which to colour bars.
    `void` | `setBarColour(int colour)` Determines the colours of the bars to be displayed on the chart.
    `void` | `setBarGap(float gap)` Sets the gap between adjacent bars.
    `void` | `setBarLabels(java.lang.String[] labels)` Sets the bar names to be displayed as axis labels.
    `void` | `setBarPadding(float padding)` Sets the padding between adjacent bars.
    `void` | `setCategoryAxisAt(float value)` Sets the position of the category axis.
    `void` | `setCategoryAxisLabel(java.lang.String label)` Sets the category axis label.
    `void` | `setCategoryFormat(java.lang.String format)` Sets the numerical format for numbers shown on the category axis.
    `void` | `setData(float[] values)` Sets the data values to be displayed in the chart.
    `void` | `setLogValues(boolean isLog)` Determines whether or not the values represented by the length of each bar should be log10-scaled.
    `void` | `setMaxValue(float maxVal)` Sets the maximum value for the bar chart.
    `void` | `setMinValue(float minVal)` Sets the minimum value for the bar chart.
    `void` | `setReverseCategories(boolean reverse)` Determines if the order of the category values should be reversed or not.
    `void` | `setValueAxisLabel(java.lang.String label)` Sets the value axis label.
    `void` | `setValueFormat(java.lang.String format)` Sets the numerical format for numbers shown on the value axis.
    `void` | `showCategoryAxis(boolean showAxis)` Determines whether or not the category axis is drawn.
    `void` | `showValueAxis(boolean showAxis)` Determines whether or not the value axis is drawn.
    `void` | `transposeAxes(boolean transpose)` Determines if the axes should be transposed (so that categories appear on the vertical axis and values on the horizontal axis).
    `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

    - #### BarChart

          public BarChart(processing.core.PApplet parent)

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

  - ### Method Detail

    - #### setData

          public void setData(float[] values)

      Sets the data values to be displayed in the chart. Each item in the given array is assumed to be in a linear sequence of equal width.
      Parameters:
        `values` - Sequence of values to chart.

    - #### getData

          public float[] getData()

      Reports the data values used to calculate bar lengths in the chart.
      Returns:
        Sequence of data values represented by the bar lengths in the chart.

    - #### draw

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

      Draws the bar 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. The x value of the dataPoint should correspond to the bar number starting at 0. The x location will be the midpoint of the bar corresponding to the data point's bar number. The location returned 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. The x-value of the returned data point corresponds to the zero-indexed counter of the number of bars (i.e if the screen location falls within the first bar, the x-value will be 0, if it falls within the second 1 will be returned etc.).
      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.

    - #### getNumBars

          public int getNumBars()

      Reports the number of bars in the bar chart. This value will include any bars that happen to have a height of 0.
      Returns:
        Number of bars in the bar chart.

    - #### setLogValues

          public void setLogValues(boolean isLog)

      Determines whether or not the values represented by the length of each bar should be log10-scaled.
      Parameters:
        `isLog` - True if values are to be log10-scaled or false if linear.

    - #### setMinValue

          public void setMinValue(float minVal)

      Sets the minimum value for the bar chart. Can be used to ensure multiple charts can share the same origin. If the given value is `Float.NaN`, then the minimum value will be set to the minimum of the data values in the chart.
      Parameters:
        `minVal` - Minimum value to use for scaling bar lengths or `Float.NaN` if data minimum is to be used.

    - #### getMinValue

          public float getMinValue()

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

    - #### getMaxValue

          public float getMaxValue()

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

    - #### setMaxValue

          public void setMaxValue(float maxVal)

      Sets the maximum value for the bar chart. Can be used to ensure multiple charts are scaled to the same maximum. If the given value is `Float.NaN`, then the maximum value will be set to the maximum of the data values in the chart.
      Parameters:
        `maxVal` - Maximum value to use for scaling bar lengths or `Float.NaN` if data maximum is to be used.

    - #### setCategoryAxisAt

          public void setCategoryAxisAt(float value)

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

    - #### setBarLabels

          public void setBarLabels(java.lang.String[] labels)

      Sets the bar names to be displayed as axis labels. If set to null, the category number is displayed in the axis.
      Parameters:
        `labels` - Array of labels corresponding to each of the bars in the chart.

    - #### showValueAxis

          public void showValueAxis(boolean showAxis)

      Determines whether or not the value axis is drawn.
      Parameters:
        `showAxis` - Value axis is drawn if true.

    - #### showCategoryAxis

          public void showCategoryAxis(boolean showAxis)

      Determines whether or not the category axis is drawn.
      Parameters:
        `showAxis` - Category axis is drawn if true.

    - #### transposeAxes

          public void transposeAxes(boolean transpose)

      Determines if the axes should be transposed (so that categories appear on the vertical axis and values on the horizontal axis).
      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.

    - #### setBarGap

          public void setBarGap(float gap)

      Sets the gap between adjacent bars.
      Parameters:
        `gap` - Gap between adjacent bars in pixel units.

    - #### setBarPadding

          public void setBarPadding(float padding)

      Sets the padding between adjacent bars. Unlike barGap, this value will give a symmetrical padding around each bar. Can be useful when overlaying bars of different thicknesses.
      Parameters:
        `padding` - Padding around bars in pixel units.

    - #### setReverseCategories

          public void setReverseCategories(boolean reverse)

      Determines if the order of the category values should be reversed or not.
      Parameters:
        `reverse` - Category order reversed if true.

    - #### setValueFormat

          public void setValueFormat(java.lang.String format)

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

    - #### setCategoryFormat

          public void setCategoryFormat(java.lang.String format)

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

    - #### setCategoryAxisLabel

          public void setCategoryAxisLabel(java.lang.String label)

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

    - #### setValueAxisLabel

          public void setValueAxisLabel(java.lang.String label)

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

    - #### setBarColour

          public void setBarColour(int colour)

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

    - #### setBarColour

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

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