Class 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

         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}
         };
         
        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:
         x-value = x-offset + (column-index * x-interval)
         

        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:
         y-value = y-offset + (column-index * y-interval)
         

        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.