Package org.tc33.jheatchart

## Class HeatChart

- java.lang.Object
- - org.tc33.jheatchart.HeatChart

-     public class HeatChart
      extends java.lang.Object

  The `HeatChart` class describes a chart which can display 3-dimensions of values - x,y and z, where x and y are the usual 2-dimensional axis and z is portrayed by colour intensity. Heat charts are sometimes known as heat maps.

  Use of this chart would typically involve 3 steps:

  1. Construction of a new instance, providing the necessary z-values.
  2. Configure the visual settings.
  3. A call to either `getChartImage()` or `saveToFile(String)`.

  ### Instantiation

  Construction of a new `HeatChart` instance is through its one constructor which takes a 2-dimensional array of `doubles` which should contain the z-values for the chart. Consider this array to be the grid of values which will instead be represented as colours in the chart.

  Setting of the x-values and y-values which are displayed along the appropriate axis is optional, and by default will simply display the values 0 to n-1, where n is the number of rows or columns. Otherwise, the x/y axis values can be set with the `setXValues` and `setYValues` methods. Both methods are overridden with two forms:

  #### Object axis values

  The simplist way to set the axis values is to use the methods which take an array of Object[]. This array must have the same length as the number of columns for setXValues and same as the number of rows for setYValues. The string representation of the objects will then be used as the axis values.

  #### Offset and Interval

  This is convenient way of defining numerical values along the axis. One of the two methods takes an interval and an offset for either the x or y axis. These parameters supply the necessary information to describe the values based upon the z-value indexes. The quantity of x-values and y-values is already known from the lengths of the z-values array dimensions. Then the offset parameters indicate what the first value will be, with the intervals providing the increment from one column or row to the next.

  Consider an example:

  >      double[][] zValues = new double[][]{
  >                     {1.2, 1.3, 1.5},
  >                     {1.0, 1.1, 1.6},
  >                     {0.7, 0.9, 1.3}
  >      };

  >      double xOffset = 1.0;
  >      double yOffset = 0.0;
  >      double xInterval = 1.0;
  >      double yInterval = 2.0;

  >      chart.setXValues(xOffset, xInterval);
  >      chart.setYValues(yOffset, yInterval);

  In this example, the z-values range from 0.7 to 1.6. The x-values range from the xOffset value 1.0 to 4.0, which is calculated as the number of x-values multiplied by the xInterval, shifted by the xOffset of 1.0. The y-values are calculated in the same way to give a range of values from 0.0 to 6.0.

  ### Configuration

  This step is optional. By default the heat chart will be generated without a title or labels on the axis, and the colouring of the heat map will be in grayscale. A large range of configuration options are available to customise the chart. All customisations are available through simple accessor methods. See the javadoc of each of the methods for more information.

  ### Output

  The generated heat chart can be obtained in two forms, using the following methods:

  - getChartImage() - The chart will be returned as a `BufferedImage` object that can be used in any number of ways, most notably it can be inserted into a Swing component, for use in a GUI application.
  - saveToFile(File) - The chart will be saved to the file system at the file location specified as a parameter. The image format that the image will be saved in is derived from the extension of the file name.
  Note: The chart image will not actually be created until either saveToFile(File) or getChartImage() are called, and will be regenerated on each successive call.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static double` | `SCALE_EXPONENTIAL` | A basic exponential scale value of 3.0.
    `static double` | `SCALE_LINEAR` | The linear scale value of 1.0.
    `static double` | `SCALE_LOGARITHMIC` | A basic logarithmic scale value of 0.3.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `HeatChart​(double[][] zValues)` | Constructs a heatmap for the given z-values against x/y-values that by default will be the values 0 to n-1, where n is the number of columns or rows.
    `HeatChart​(double[][] zValues, double low, double high)` | Constructs a heatmap for the given z-values against x/y-values that by default will be the values 0 to n-1, where n is the number of columns or rows.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.awt.Color` | `getAxisColour()` | Returns the colour that is set to be used for the axis bars.
    `java.awt.Color` | `getAxisLabelColour()` | Returns the current colour of the axis labels.
    `java.awt.Font` | `getAxisLabelsFont()` | Returns the font that describes the visual style of the labels of the axis.
    `int` | `getAxisThickness()` | Returns the width of the axis bars in pixels.
    `java.awt.Color` | `getAxisValuesColour()` | Returns the colour of the axis values as they will be painted along the axis bars.
    `java.awt.Font` | `getAxisValuesFont()` | Returns the font which describes the visual style of the axis values.
    `java.awt.Color` | `getBackgroundColour()` | Returns an object that represents the colour to be used as the background for the whole chart.
    `int` | `getCellHeight()` | Deprecated. As of release 0.6, replaced by `getCellSize()`
    `java.awt.Dimension` | `getCellSize()` | Returns the size of each individual data cell that constitutes a value in the x,y,z space.
    `int` | `getCellWidth()` | Deprecated. As of release 0.6, replaced by `getCellSize()`
    `void` | `getChartGraphics​(java.awt.Graphics2D chartGraphics)` | Writes the heatmap to chartGraphics - added by JE
    `int` | `getChartHeight()` | Deprecated. As of release 0.6, replaced by `getChartSize()`
    `java.awt.Image` | `getChartImage()` | Generates and returns a new chart `Image` configured according to this object's currently held settings.
    `java.awt.Image` | `getChartImage​(boolean alpha)` | Generates and returns a new chart `Image` configured according to this object's currently held settings.
    `int` | `getChartMargin()` | Returns the width of the margin in pixels to be left as empty space around the heat map element.
    `java.awt.Dimension` | `getChartSize()` | Returns the size of the chart in pixels as calculated according to the cell dimensions, chart margin and other size settings.
    `int` | `getChartWidth()` | Deprecated. As of release 0.6, replaced by `getChartSize()`
    `double` | `getColourScale()` | Returns the scale that is currently in use to map z-value to colour.
    `double` | `getHighValue()` | Returns the high value.
    `java.awt.Color` | `getHighValueColour()` | Returns the colour that is currently to be displayed for the heat map cells with the highest z-value in the dataset.
    `double` | `getLowValue()` | Returns the low value.
    `java.awt.Color` | `getLowValueColour()` | Returns the colour that is currently to be displayed for the heat map cells with the lowest z-value in the dataset.
    `java.lang.String` | `getTitle()` | Returns the String that will be used as the title of any successive calls to generate a chart.
    `java.awt.Color` | `getTitleColour()` | Returns the `Color` that represents the colour the title text should be painted in.
    `java.awt.Font` | `getTitleFont()` | Returns the `Font` that describes the visual style of the title.
    `java.lang.String` | `getXAxisLabel()` | Returns the String that will be displayed as a description of the x-axis in any generated charts.
    `int` | `getXAxisValuesFrequency()` | Returns the frequency of the values displayed along the x-axis.
    `java.lang.Object[]` | `getXValues()` | Returns the x-values which are currently set to display along the x-axis.
    `java.lang.String` | `getYAxisLabel()` | Returns the String that will be displayed as a description of the y-axis in any generated charts.
    `int` | `getYAxisValuesFrequency()` | Returns the frequency of the values displayed along the y-axis.
    `java.lang.Object[]` | `getYValues()` | Returns the y-values which are currently set to display along the y-axis.
    `double[][]` | `getZValues()` | Returns the 2-dimensional array of z-values currently in use.
    `boolean` | `isShowXAxisValues()` | Returns whether axis values are to be shown at all for the x-axis.
    `boolean` | `isShowYAxisValues()` | Returns whether axis values are to be shown at all for the y-axis.
    `boolean` | `isXValuesHorizontal()` | Returns whether the text of the values along the x-axis are to be drawn horizontally left-to-right, or vertically top-to-bottom.
    `boolean` | `isYValuesHorizontal()` | Returns whether the text of the values along the y-axis are to be drawn horizontally left-to-right, or vertically top-to-bottom.
    `static double` | `max​(double[][] values)` | Finds and returns the maximum value in a 2-dimensional array of doubles.
    `static double` | `min​(double[][] values)` | Finds and returns the minimum value in a 2-dimensional array of doubles.
    `void` | `saveToFile​(java.io.File outputFile)` | Generates a new chart `Image` based upon the currently held settings and then attempts to save that image to disk, to the location provided as a File parameter.
    `void` | `setAxisColour​(java.awt.Color axisColour)` | Sets the colour to be used on the axis bars.
    `void` | `setAxisLabelColour​(java.awt.Color axisLabelColour)` | Sets the colour of the text displayed as axis labels.
    `void` | `setAxisLabelsFont​(java.awt.Font axisLabelsFont)` | Sets the font that describes the visual style of the axis labels.
    `void` | `setAxisThickness​(int axisThickness)` | Sets the width of the axis bars in pixels.
    `void` | `setAxisValuesColour​(java.awt.Color axisValuesColour)` | Sets the colour to be used for the axis values as they will be painted along the axis bars.
    `void` | `setAxisValuesFont​(java.awt.Font axisValuesFont)` | Sets the font which describes the visual style of the axis values.
    `void` | `setBackgroundColour​(java.awt.Color backgroundColour)` | Sets the colour to be used on the background of the chart.
    `void` | `setCellHeight​(int cellHeight)` | Deprecated. As of release 0.6, replaced by `setCellSize(Dimension)`
    `void` | `setCellSize​(java.awt.Dimension cellSize)` | Sets the size of each individual cell that constitutes a value in x,y,z data space.
    `void` | `setCellWidth​(int cellWidth)` | Deprecated. As of release 0.6, replaced by `setCellSize(Dimension)`
    `void` | `setChartMargin​(int margin)` | Sets the width of the margin in pixels to be left as empty space around the heat map element.
    `void` | `setColourScale​(double colourScale)` | Sets the scale that is currently in use to map z-value to colour.
    `void` | `setHighValueColour​(java.awt.Color highValueColour)` | Sets the colour to be used to fill cells of the heat map with the highest z-values in the dataset.
    `void` | `setLowValueColour​(java.awt.Color lowValueColour)` | Sets the colour to be used to fill cells of the heat map with the lowest z-values in the dataset.
    `void` | `setShowXAxisValues​(boolean showXAxisValues)` | Sets whether axis values are to be shown at all for the x-axis.
    `void` | `setShowYAxisValues​(boolean showYAxisValues)` | Sets whether axis values are to be shown at all for the y-axis.
    `void` | `setTitle​(java.lang.String title)` | Sets the String that will be used as the title of any successive calls to generate a chart.
    `void` | `setTitleColour​(java.awt.Color titleColour)` | Sets the `Color` that describes the colour to be used for the chart title String.
    `void` | `setTitleFont​(java.awt.Font titleFont)` | Sets a new `Font` to be used in rendering the chart's title String.
    `void` | `setXAxisLabel​(java.lang.String xAxisLabel)` | Sets the String that will be displayed as a description of the x-axis in any generated charts.
    `void` | `setXAxisValuesFrequency​(int axisValuesFrequency)` | Sets the frequency of the values displayed along the x-axis.
    `void` | `setXValues​(double xOffset, double xInterval)` | Sets the x-values which are plotted along the x-axis.
    `void` | `setXValues​(java.lang.Object[] xValues)` | Sets the x-values which are plotted along the x-axis.
    `void` | `setXValuesHorizontal​(boolean xValuesHorizontal)` | Sets whether the text of the values along the x-axis should be drawn horizontally left-to-right, or vertically top-to-bottom.
    `void` | `setYAxisLabel​(java.lang.String yAxisLabel)` | Sets the String that will be displayed as a description of the y-axis in any generated charts.
    `void` | `setYAxisValuesFrequency​(int axisValuesFrequency)` | Sets the frequency of the values displayed along the y-axis.
    `void` | `setYValues​(double yOffset, double yInterval)` | Sets the y-values which are plotted along the y-axis.
    `void` | `setYValues​(java.lang.Object[] yValues)` | Sets the y-values which are plotted along the y-axis.
    `void` | `setYValuesHorizontal​(boolean yValuesHorizontal)` | Sets whether the text of the values along the y-axis should be drawn horizontally left-to-right, or vertically top-to-bottom.
    `void` | `setZValues​(double[][] zValues)` | Replaces the z-values array.
    `void` | `setZValues​(double[][] zValues, double low, double high)` | Replaces the z-values array.

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

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

- - ### Field Detail

    - #### SCALE_LOGARITHMIC

          public static final double SCALE_LOGARITHMIC

      A basic logarithmic scale value of 0.3.
      See Also:
        Constant Field Values

    - #### SCALE_LINEAR

          public static final double SCALE_LINEAR

      The linear scale value of 1.0.
      See Also:
        Constant Field Values

    - #### SCALE_EXPONENTIAL

          public static final double SCALE_EXPONENTIAL

      A basic exponential scale value of 3.0.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### HeatChart

          public HeatChart​(double[][] zValues)

      Constructs a heatmap for the given z-values against x/y-values that by default will be the values 0 to n-1, where n is the number of columns or rows.
      Parameters:
        `zValues` - the z-values, where each element is a row of z-values in the resultant heat chart.

    - #### HeatChart

          public HeatChart​(double[][] zValues,
                           double low,
                           double high)

      Constructs a heatmap for the given z-values against x/y-values that by default will be the values 0 to n-1, where n is the number of columns or rows.
      Parameters:
        `zValues` - the z-values, where each element is a row of z-values in the resultant heat chart.
        `low` - the minimum possible value, which may or may not appear in the z-values.
        `high` - the maximum possible value, which may or may not appear in the z-values.

  - ### Method Detail

    - #### getLowValue

          public double getLowValue()

      Returns the low value. This is the value at which the low value colour will be applied.
      Returns:
        the low value.

    - #### getHighValue

          public double getHighValue()

      Returns the high value. This is the value at which the high value colour will be applied.
      Returns:
        the high value.

    - #### getZValues

          public double[][] getZValues()

      Returns the 2-dimensional array of z-values currently in use. Each element is a double array which represents one row of the heat map, or all the z-values for one y-value.
      Returns:
        an array of the z-values in current use, that is, those values which will define the colour of each cell in the resultant heat map.

    - #### setZValues

          public void setZValues​(double[][] zValues)

      Replaces the z-values array. See the `setZValues(double[][], double, double)` method for an example of z-values. The smallest and largest values in the array are used as the minimum and maximum values respectively.
      Parameters:
        `zValues` - the array to replace the current array with. The number of elements in each inner array must be identical.

    - #### setZValues

          public void setZValues​(double[][] zValues,
                                 double low,
                                 double high)

      Replaces the z-values array. The number of elements should match the number of y-values, with each element containing a double array with an equal number of elements that matches the number of x-values. Use this method where the minimum and maximum values possible are not contained within the dataset.

      ## Example

      <blockcode>

           new double[][]{
             {1.0,1.2,1.4},
             {1.2,1.3,1.5},
             {0.9,1.3,1.2},
             {0.8,1.6,1.1}
           };

      </blockcode> The above zValues array is equivalent to:

      y | 1.0 | 1.2 | 1.4
      1.2 | 1.3 | 1.5
      0.9 | 1.3 | 1.2
      0.8 | 1.6 | 1.1
      | x

      Parameters:
        `zValues` - the array to replace the current array with. The number of elements in each inner array must be identical.
        `low` - the minimum possible value, which may or may not appear in the z-values.
        `high` - the maximum possible value, which may or may not appear in the z-values.

    - #### setXValues

          public void setXValues​(double xOffset,
                                 double xInterval)

      Sets the x-values which are plotted along the x-axis. The x-values are calculated based upon the indexes of the z-values array: <blockcode>

           x-value = x-offset + (column-index * x-interval)

      </blockcode>

      The x-interval defines the gap between each x-value and the x-offset is applied to each value to offset them all from zero.

      Alternatively the x-values can be set more directly with the `setXValues(Object[])` method.

      Parameters:
        `xOffset` - an offset value to be applied to the index of each z-value element.
        `xInterval` - an interval that will separate each x-value item.

    - #### setXValues

          public void setXValues​(java.lang.Object[] xValues)

      Sets the x-values which are plotted along the x-axis. The given x-values array must be the same length as the z-values array has columns. Each of the x-values elements will be displayed according to their toString representation.
      Parameters:
        `xValues` - an array of elements to be displayed as values along the x-axis.

    - #### setYValues

          public void setYValues​(double yOffset,
                                 double yInterval)

      Sets the y-values which are plotted along the y-axis. The y-values are calculated based upon the indexes of the z-values array: <blockcode>

           y-value = y-offset + (column-index * y-interval)

      </blockcode>

      The y-interval defines the gap between each y-value and the y-offset is applied to each value to offset them all from zero.

      Alternatively the y-values can be set more directly with the `setYValues(Object[])` method.

      Parameters:
        `yOffset` - an offset value to be applied to the index of each z-value element.
        `yInterval` - an interval that will separate each y-value item.

    - #### setYValues

          public void setYValues​(java.lang.Object[] yValues)

      Sets the y-values which are plotted along the y-axis. The given y-values array must be the same length as the z-values array has columns. Each of the y-values elements will be displayed according to their toString representation.
      Parameters:
        `yValues` - an array of elements to be displayed as values along the y-axis.

    - #### getXValues

          public java.lang.Object[] getXValues()

      Returns the x-values which are currently set to display along the x-axis. The array that is returned is either that which was explicitly set with `setXValues(Object[])` or that was generated from the offset and interval that were given to `setXValues(double, double)`, in which case the object type of each element will be `Double`.
      Returns:
        an array of the values that are to be displayed along the x-axis.

    - #### getYValues

          public java.lang.Object[] getYValues()

      Returns the y-values which are currently set to display along the y-axis. The array that is returned is either that which was explicitly set with `setYValues(Object[])` or that was generated from the offset and interval that were given to `setYValues(double, double)`, in which case the object type of each element will be `Double`.
      Returns:
        an array of the values that are to be displayed along the y-axis.

    - #### setXValuesHorizontal

          public void setXValuesHorizontal​(boolean xValuesHorizontal)

      Sets whether the text of the values along the x-axis should be drawn horizontally left-to-right, or vertically top-to-bottom.
      Parameters:
        `xValuesHorizontal` - true if x-values should be drawn horizontally, false if they should be drawn vertically.

    - #### isXValuesHorizontal

          public boolean isXValuesHorizontal()

      Returns whether the text of the values along the x-axis are to be drawn horizontally left-to-right, or vertically top-to-bottom.
      Returns:
        true if the x-values will be drawn horizontally, false if they will be drawn vertically.

    - #### setYValuesHorizontal

          public void setYValuesHorizontal​(boolean yValuesHorizontal)

      Sets whether the text of the values along the y-axis should be drawn horizontally left-to-right, or vertically top-to-bottom.
      Parameters:
        `yValuesHorizontal` - true if y-values should be drawn horizontally, false if they should be drawn vertically.

    - #### isYValuesHorizontal

          public boolean isYValuesHorizontal()

      Returns whether the text of the values along the y-axis are to be drawn horizontally left-to-right, or vertically top-to-bottom.
      Returns:
        true if the y-values will be drawn horizontally, false if they will be drawn vertically.

    - #### setCellWidth

          @Deprecated
          public void setCellWidth​(int cellWidth)

      Deprecated.
      As of release 0.6, replaced by `setCellSize(Dimension)`
      Sets the width of each individual cell that constitutes a value in x,y,z data space. By setting the cell width, any previously set chart width will be overwritten with a value calculated based upon this value and the number of cells in there are along the x-axis.
      Parameters:
        `cellWidth` - the new width to use for each individual data cell.

    - #### getCellWidth

          @Deprecated
          public int getCellWidth()

      Deprecated.
      As of release 0.6, replaced by `getCellSize()`
      Returns the width of each individual data cell that constitutes a value in the x,y,z space.
      Returns:
        the width of each cell.

    - #### setCellHeight

          @Deprecated
          public void setCellHeight​(int cellHeight)

      Deprecated.
      As of release 0.6, replaced by `setCellSize(Dimension)`
      Sets the height of each individual cell that constitutes a value in x,y,z data space. By setting the cell height, any previously set chart height will be overwritten with a value calculated based upon this value and the number of cells in there are along the y-axis.
      Parameters:
        `cellHeight` - the new height to use for each individual data cell.

    - #### getCellHeight

          @Deprecated
          public int getCellHeight()

      Deprecated.
      As of release 0.6, replaced by `getCellSize()`
      Returns the height of each individual data cell that constitutes a value in the x,y,z space.
      Returns:
        the height of each cell.

    - #### setCellSize

          public void setCellSize​(java.awt.Dimension cellSize)

      Sets the size of each individual cell that constitutes a value in x,y,z data space. By setting the cell size, any previously set chart size will be overwritten with a value calculated based upon this value and the number of cells along each axis.
      Parameters:
        `cellSize` - the new size to use for each individual data cell.
      Since:
        0.6

    - #### getCellSize

          public java.awt.Dimension getCellSize()

      Returns the size of each individual data cell that constitutes a value in the x,y,z space.
      Returns:
        the size of each individual data cell.
      Since:
        0.6

    - #### getChartWidth

          @Deprecated
          public int getChartWidth()

      Deprecated.
      As of release 0.6, replaced by `getChartSize()`
      Returns the width of the chart in pixels as calculated according to the cell dimensions, chart margin and other size settings.
      Returns:
        the width in pixels of the chart image to be generated.

    - #### getChartHeight

          @Deprecated
          public int getChartHeight()

      Deprecated.
      As of release 0.6, replaced by `getChartSize()`
      Returns the height of the chart in pixels as calculated according to the cell dimensions, chart margin and other size settings.
      Returns:
        the height in pixels of the chart image to be generated.

    - #### getChartSize

          public java.awt.Dimension getChartSize()

      Returns the size of the chart in pixels as calculated according to the cell dimensions, chart margin and other size settings.
      Returns:
        the size in pixels of the chart image to be generated.
      Since:
        0.6

    - #### getTitle

          public java.lang.String getTitle()

      Returns the String that will be used as the title of any successive calls to generate a chart.
      Returns:
        the title of the chart.

    - #### setTitle

          public void setTitle​(java.lang.String title)

      Sets the String that will be used as the title of any successive calls to generate a chart. The title will be displayed centralised horizontally at the top of any generated charts.

      If the title is set to `null` then no title will be displayed.

      Defaults to null.

      Parameters:
        `title` - the chart title to set.

    - #### getXAxisLabel

          public java.lang.String getXAxisLabel()

      Returns the String that will be displayed as a description of the x-axis in any generated charts.
      Returns:
        the display label describing the x-axis.

    - #### setXAxisLabel

          public void setXAxisLabel​(java.lang.String xAxisLabel)

      Sets the String that will be displayed as a description of the x-axis in any generated charts. The label will be displayed horizontally central of the x-axis bar.

      If the xAxisLabel is set to `null` then no label will be displayed.

      Defaults to null.

      Parameters:
        `xAxisLabel` - the label to be displayed describing the x-axis.

    - #### getYAxisLabel

          public java.lang.String getYAxisLabel()

      Returns the String that will be displayed as a description of the y-axis in any generated charts.
      Returns:
        the display label describing the y-axis.

    - #### setYAxisLabel

          public void setYAxisLabel​(java.lang.String yAxisLabel)

      Sets the String that will be displayed as a description of the y-axis in any generated charts. The label will be displayed horizontally central of the y-axis bar.

      If the yAxisLabel is set to `null` then no label will be displayed.

      Defaults to null.

      Parameters:
        `yAxisLabel` - the label to be displayed describing the y-axis.

    - #### getChartMargin

          public int getChartMargin()

      Returns the width of the margin in pixels to be left as empty space around the heat map element.
      Returns:
        the size of the margin to be left blank around the edge of the chart.

    - #### setChartMargin

          public void setChartMargin​(int margin)

      Sets the width of the margin in pixels to be left as empty space around the heat map element. If a title is set then half the margin will be directly above the title and half directly below it. Where axis labels are set then the axis labels may sit partially in the margin.

      Defaults to 20 pixels.

      Parameters:
        `margin` - the new margin to be left as blank space around the heat map.

    - #### getBackgroundColour

          public java.awt.Color getBackgroundColour()

      Returns an object that represents the colour to be used as the background for the whole chart.
      Returns:
        the colour to be used to fill the chart background.

    - #### setBackgroundColour

          public void setBackgroundColour​(java.awt.Color backgroundColour)

      Sets the colour to be used on the background of the chart. A transparent background can be set by setting a background colour with an alpha value. The transparency will only be effective when the image is saved as a png or gif.

      Defaults to `Color.WHITE`.

      Parameters:
        `backgroundColour` - the new colour to be set as the background fill.

    - #### getTitleFont

          public java.awt.Font getTitleFont()

      Returns the `Font` that describes the visual style of the title.
      Returns:
        the Font that will be used to render the title.

    - #### setTitleFont

          public void setTitleFont​(java.awt.Font titleFont)

      Sets a new `Font` to be used in rendering the chart's title String.

      Defaults to Sans-Serif, BOLD, 16 pixels.

      Parameters:
        `titleFont` - the Font that should be used when rendering the chart title.

    - #### getTitleColour

          public java.awt.Color getTitleColour()

      Returns the `Color` that represents the colour the title text should be painted in.
      Returns:
        the currently set colour to be used in painting the chart title.

    - #### setTitleColour

          public void setTitleColour​(java.awt.Color titleColour)

      Sets the `Color` that describes the colour to be used for the chart title String.

      Defaults to `Color.BLACK`.

      Parameters:
        `titleColour` - the colour to paint the chart's title String.

    - #### getAxisThickness

          public int getAxisThickness()

      Returns the width of the axis bars in pixels. Both axis bars have the same thickness.
      Returns:
        the thickness of the axis bars in pixels.

    - #### setAxisThickness

          public void setAxisThickness​(int axisThickness)

      Sets the width of the axis bars in pixels. Both axis bars use the same thickness.

      Defaults to 2 pixels.

      Parameters:
        `axisThickness` - the thickness to use for the axis bars in any newly generated charts.

    - #### getAxisColour

          public java.awt.Color getAxisColour()

      Returns the colour that is set to be used for the axis bars. Both axis bars use the same colour.
      Returns:
        the colour in use for the axis bars.

    - #### setAxisColour

          public void setAxisColour​(java.awt.Color axisColour)

      Sets the colour to be used on the axis bars. Both axis bars use the same colour.

      Defaults to `Color.BLACK`.

      Parameters:
        `axisColour` - the colour to be set for use on the axis bars.

    - #### getAxisLabelsFont

          public java.awt.Font getAxisLabelsFont()

      Returns the font that describes the visual style of the labels of the axis. Both axis' labels use the same font.
      Returns:
        the font used to define the visual style of the axis labels.

    - #### setAxisLabelsFont

          public void setAxisLabelsFont​(java.awt.Font axisLabelsFont)

      Sets the font that describes the visual style of the axis labels. Both axis' labels use the same font.

      Defaults to Sans-Serif, PLAIN, 12 pixels.

      Parameters:
        `axisLabelsFont` - the font to be used to define the visual style of the axis labels.

    - #### getAxisLabelColour

          public java.awt.Color getAxisLabelColour()

      Returns the current colour of the axis labels. Both labels use the same colour.
      Returns:
        the colour of the axis label text.

    - #### setAxisLabelColour

          public void setAxisLabelColour​(java.awt.Color axisLabelColour)

      Sets the colour of the text displayed as axis labels. Both labels use the same colour.

      Defaults to Color.BLACK.

      Parameters:
        `axisLabelColour` - the colour to use for the axis label text.

    - #### getAxisValuesFont

          public java.awt.Font getAxisValuesFont()

      Returns the font which describes the visual style of the axis values. The axis values are those values displayed alongside the axis bars at regular intervals. Both axis use the same font.
      Returns:
        the font in use for the axis values.

    - #### setAxisValuesFont

          public void setAxisValuesFont​(java.awt.Font axisValuesFont)

      Sets the font which describes the visual style of the axis values. The axis values are those values displayed alongside the axis bars at regular intervals. Both axis use the same font.

      Defaults to Sans-Serif, PLAIN, 10 pixels.

      Parameters:
        `axisValuesFont` - the font that should be used for the axis values.

    - #### getAxisValuesColour

          public java.awt.Color getAxisValuesColour()

      Returns the colour of the axis values as they will be painted along the axis bars. Both axis use the same colour.
      Returns:
        the colour of the values displayed along the axis bars.

    - #### setAxisValuesColour

          public void setAxisValuesColour​(java.awt.Color axisValuesColour)

      Sets the colour to be used for the axis values as they will be painted along the axis bars. Both axis use the same colour.

      Defaults to Color.BLACK.

      Parameters:
        `axisValuesColour` - the new colour to be used for the axis bar values.

    - #### getXAxisValuesFrequency

          public int getXAxisValuesFrequency()

      Returns the frequency of the values displayed along the x-axis. The frequency is how many columns in the x-dimension have their value displayed. A frequency of 2 would mean every other column has a value shown and a frequency of 3 would mean every third column would be given a value.
      Returns:
        the frequency of the values displayed against columns.

    - #### setXAxisValuesFrequency

          public void setXAxisValuesFrequency​(int axisValuesFrequency)

      Sets the frequency of the values displayed along the x-axis. The frequency is how many columns in the x-dimension have their value displayed. A frequency of 2 would mean every other column has a value and a frequency of 3 would mean every third column would be given a value.

      Defaults to 1. Every column is given a value.

      Parameters:
        `axisValuesFrequency` - the frequency of the values displayed against columns, where 1 is every column and 2 is every other column.

    - #### getYAxisValuesFrequency

          public int getYAxisValuesFrequency()

      Returns the frequency of the values displayed along the y-axis. The frequency is how many rows in the y-dimension have their value displayed. A frequency of 2 would mean every other row has a value and a frequency of 3 would mean every third row would be given a value.
      Returns:
        the frequency of the values displayed against rows.

    - #### setYAxisValuesFrequency

          public void setYAxisValuesFrequency​(int axisValuesFrequency)

      Sets the frequency of the values displayed along the y-axis. The frequency is how many rows in the y-dimension have their value displayed. A frequency of 2 would mean every other row has a value and a frequency of 3 would mean every third row would be given a value.

      Defaults to 1. Every row is given a value.

      Parameters:
        `axisValuesFrequency` - the frequency of the values displayed against rows, where 1 is every row and 2 is every other row.

    - #### isShowXAxisValues

          public boolean isShowXAxisValues()

      Returns whether axis values are to be shown at all for the x-axis.

      If axis values are not shown then more space is allocated to the heat map.

      Returns:
        true if the x-axis values will be displayed, false otherwise.

    - #### setShowXAxisValues

          public void setShowXAxisValues​(boolean showXAxisValues)

      Sets whether axis values are to be shown at all for the x-axis.

      If axis values are not shown then more space is allocated to the heat map.

      Defaults to true.

      Parameters:
        `showXAxisValues` - true if x-axis values should be displayed, false if they should be hidden.

    - #### isShowYAxisValues

          public boolean isShowYAxisValues()

      Returns whether axis values are to be shown at all for the y-axis.

      If axis values are not shown then more space is allocated to the heat map.

      Returns:
        true if the y-axis values will be displayed, false otherwise.

    - #### setShowYAxisValues

          public void setShowYAxisValues​(boolean showYAxisValues)

      Sets whether axis values are to be shown at all for the y-axis.

      If axis values are not shown then more space is allocated to the heat map.

      Defaults to true.

      Parameters:
        `showYAxisValues` - true if y-axis values should be displayed, false if they should be hidden.

    - #### getHighValueColour

          public java.awt.Color getHighValueColour()

      Returns the colour that is currently to be displayed for the heat map cells with the highest z-value in the dataset.

      The full colour range will go through each RGB step between the high value colour and the low value colour.

      Returns:
        the colour in use for cells of the highest z-value.

    - #### setHighValueColour

          public void setHighValueColour​(java.awt.Color highValueColour)

      Sets the colour to be used to fill cells of the heat map with the highest z-values in the dataset.

      The full colour range will go through each RGB step between the high value colour and the low value colour.

      Defaults to Color.BLACK.

      Parameters:
        `highValueColour` - the colour to use for cells of the highest z-value.

    - #### getLowValueColour

          public java.awt.Color getLowValueColour()

      Returns the colour that is currently to be displayed for the heat map cells with the lowest z-value in the dataset.

      The full colour range will go through each RGB step between the high value colour and the low value colour.

      Returns:
        the colour in use for cells of the lowest z-value.

    - #### setLowValueColour

          public void setLowValueColour​(java.awt.Color lowValueColour)

      Sets the colour to be used to fill cells of the heat map with the lowest z-values in the dataset.

      The full colour range will go through each RGB step between the high value colour and the low value colour.

      Defaults to Color.WHITE.

      Parameters:
        `lowValueColour` - the colour to use for cells of the lowest z-value.

    - #### getColourScale

          public double getColourScale()

      Returns the scale that is currently in use to map z-value to colour. A value of 1.0 will give a linear scale, which will spread the distribution of colours evenly amoungst the full range of represented z-values. A value of greater than 1.0 will give an exponential scale that will produce greater emphasis for the separation between higher values and a value between 0.0 and 1.0 will provide a logarithmic scale, with greater separation of low values.
      Returns:
        the scale factor that is being used to map from z-value to colour.

    - #### setColourScale

          public void setColourScale​(double colourScale)

      Sets the scale that is currently in use to map z-value to colour. A value of 1.0 will give a linear scale, which will spread the distribution of colours evenly amoungst the full range of represented z-values. A value of greater than 1.0 will give an exponential scale that will produce greater emphasis for the separation between higher values and a value between 0.0 and 1.0 will provide a logarithmic scale, with greater separation of low values. Values of 0.0 or less are illegal.

      Defaults to a linear scale value of 1.0.

      Parameters:
        `colourScale` - the scale that should be used to map from z-value to colour.

    - #### saveToFile

          public void saveToFile​(java.io.File outputFile)
                          throws java.io.IOException

      Generates a new chart `Image` based upon the currently held settings and then attempts to save that image to disk, to the location provided as a File parameter. The image type of the saved file will equal the extension of the filename provided, so it is essential that a suitable extension be included on the file name.

      All supported `ImageIO` file types are supported, including PNG, JPG and GIF.

      No chart will be generated until this or the related `getChartImage()` method are called. All successive calls will result in the generation of a new chart image, no caching is used.

      Parameters:
        `outputFile` - the file location that the generated image file should be written to. The File must have a suitable filename, with an extension of a valid image format (as supported by `ImageIO`).
      Throws:
        `java.io.IOException` - if the output file's filename has no extension or if there the file is unable to written to. Reasons for this include a non-existant file location (check with the File exists() method on the parent directory), or the permissions of the write location may be incorrect.

    - #### getChartImage

          public java.awt.Image getChartImage​(boolean alpha)

      Generates and returns a new chart `Image` configured according to this object's currently held settings. The given parameter determines whether transparency should be enabled for the generated image.

      No chart will be generated until this or the related `saveToFile(File)` method are called. All successive calls will result in the generation of a new chart image, no caching is used.

      Parameters:
        `alpha` - whether to enable transparency.
      Returns:
        A newly generated chart `Image`. The returned image is a `BufferedImage`.

    - #### getChartImage

          public java.awt.Image getChartImage()

      Generates and returns a new chart `Image` configured according to this object's currently held settings. By default the image is generated with no transparency.

      No chart will be generated until this or the related `saveToFile(File)` method are called. All successive calls will result in the generation of a new chart image, no caching is used.

      Returns:
        A newly generated chart `Image`. The returned image is a `BufferedImage`.

    - #### getChartGraphics

          public void getChartGraphics​(java.awt.Graphics2D chartGraphics)

      Writes the heatmap to chartGraphics - added by JE

    - #### max

          public static double max​(double[][] values)

      Finds and returns the maximum value in a 2-dimensional array of doubles.
      Returns:
        the largest value in the array.

    - #### min

          public static double min​(double[][] values)

      Finds and returns the minimum value in a 2-dimensional array of doubles.
      Returns:
        the smallest value in the array.