Heatmap¶

This section showcases the heatmap chart. It contains examples of how to create the heatmap using the datachart.charts.Heatmap function.

The examples sequentially build on each other, going from simple to complex.

As mentioned above, the heatmap are created using the Heatmap function found in the datachart.charts module. Let's import it:

In [1]:

from datachart.charts import Heatmap

from datachart.charts import Heatmap

Double figure generation avoidence

To avoid double figure generation, the Heatmap function is preceded by the _ = operator. The double figures are generated because Heatmap returns the plt.Figure object, which is then used to save the figure locally.

Heatmap Input Attributes¶

The Heatmap function accepts the attributes of the datachart.typings.HeatmapChartAttrs type. In a nutshell, the input is a dict object containing the charts attribute, which is either a dict or a List[dict] where each dictionary contains some of the following attributes:

{
  "data": List[List[Union[int, float, None]]],                  # The data of the chart
  "style": {                                                    # The style of the heatmap (optional)
    "plot_heatmap_cmap":      Optional[str],                    # The color map of the heatmap
    "plot_heatmap_alpha":     Optional[float],                  # The heatmap alpha (opacity)
    "plot_heatmap_font_size": Optional[Union[int, float, str]], # The heatmap cell font size
    "plot_heatmap_font_color": Optional[str],                   # The heatmap cell font color
    "plot_heatmap_font_width": Optional[float],                 # The heatmap cell font width
    "plot_heatmap_font_alpha": Optional[float],                 # The heatmap cell font alpha (opacity)
  },
  "subtitle": Optional[str],                                    # The title of the chart
  "xlabel":   Optional[str],                                    # The x-axis label
  "ylabel":   Optional[str],                                    # The y-axis label

  "xticks": Optional[List[Union[int, float]]],                  # the x-axis ticks
  "xticklabels": Optional[List[Union[str, float, str]],         # the x-axis tick labels (must be same length as xticks)
  "xtickrotate": Optional[int],                                 # the x-axis tick labels rotation
  "yticks": Optional[List[Union[int, float]]],                  # the y-axis ticks
  "yticklabels": Optional[List[Union[str, float, str]],         # the y-axis tick labels (must be same length as yticks)
  "ytickrotate": Optional[int],                                 # the y-axis tick labels rotation

  "colormap": {
    "orientation": Optional[ORIENTATION],                       # the colormap orientation
  }
}

For more details, see the datachart.typings.HeatmapChartAttrs type.

Single Heatmap Chart¶

In this part, we show how to create a single heatmap chart using the Heatmap function.

Basic example. Let us first create a basic heatmap chart showing a square distribution.

The following example shows how only the charts["data"] attribute is required to draw the heatmap chart.

In [2]:

_ = Heatmap(
    {
        # add the data to the chart
        "charts": {"data": [[x + y for x in range(8)] for y in range(8)]}
    }
)

_ = Heatmap( { # add the data to the chart "charts": {"data": [[x + y for x in range(8)] for y in range(8)]} } )

Chart title and axis labels¶

To add the chart title and axis labels, simply add the title, xlabel and ylabel attributes.

In [3]:

_ = Heatmap(
    {
        "charts": {"data": [[x + y for x in range(8)] for y in range(8)]},
        # add the title
        "title": "Title",
        # add the x and y axis labels
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
    }
)

_ = Heatmap( { "charts": {"data": [[x + y for x in range(8)] for y in range(8)]}, # add the title "title": "Title", # add the x and y axis labels "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", } )

Figure size¶

To change the figure size, simply add the figsize attribute. The figsize attribute can be a tuple (width, height), values are in inches. The datachart package provides a datachart.constants.FIG_SIZE constant, which contains some of the predefined figure sizes.

In [4]:

from datachart.constants import FIG_SIZE

from datachart.constants import FIG_SIZE

In [5]:

_ = Heatmap(
    {
        "charts": {"data": [[x + y for x in range(8)] for y in range(8)]},
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        # add to determine the figure size
        "figsize": FIG_SIZE.SQUARE_SMALL,
    }
)

_ = Heatmap( { "charts": {"data": [[x + y for x in range(8)] for y in range(8)]}, "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", # add to determine the figure size "figsize": FIG_SIZE.SQUARE_SMALL, } )

Colorbar and heatmap values¶

To add the colorbar, simply add the show_colorbar attribute. In addition, to add the heatmap values, simply add the show_heatmap_values attribute.

In [6]:

_ = Heatmap(
    {
        "charts": {
            "data": [[x + y for x in range(8)] for y in range(8)],
        },
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.SQUARE_SMALL,
        # add to determine if the heatmap values should be shown
        "show_heatmap_values": True,
        # add to determine if the colorbars should be shown
        "show_colorbars": True,
    }
)

_ = Heatmap( { "charts": { "data": [[x + y for x in range(8)] for y in range(8)], }, "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.SQUARE_SMALL, # add to determine if the heatmap values should be shown "show_heatmap_values": True, # add to determine if the colorbars should be shown "show_colorbars": True, } )

Format heatmap values¶

To format the values shown in the heatmap, add the valfmt attribute, which is a string depicting how to format the heatmap values. Examples of such formats are:

Format	Description
"{x}"	Formats the value as is (no change to the value).
"{x:d}"	Formats the value as an integer.
"{x:.2f}"	Formats the value as a float with two decimal places.
"{x:.2%}"	Formats the value as a percentage with two decimal places.

Required presence of x

To format the heatmap values, the x value must be present in the string. For instance "{z:.2f}" is not a valid format, and z should be replaced with x.

Again, to help with the style settings, the datachart.constants module contains the following constants:

Constant	Description
datachart.constants.VALFMT	The predefined value formats.

In [7]:

from datachart.constants import VALFMT

from datachart.constants import VALFMT

In [8]:

_ = Heatmap(
    {
        "charts": {
            "data": [[x + y for x in range(8)] for y in range(8)],
            # add the value format
            "valfmt": VALFMT.DECIMAL,
        },
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.SQUARE_SMALL,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

_ = Heatmap( { "charts": { "data": [[x + y for x in range(8)] for y in range(8)], # add the value format "valfmt": VALFMT.DECIMAL, }, "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.SQUARE_SMALL, "show_heatmap_values": True, "show_colorbars": True, } )

Ticks and labels¶

To add the labels to the x and y axis, add the xticklabels and yticklabels attributes. The positions of the ticks are determined by the xticks and yticks attributes. To define the rotation of the labels, add the xtickrotate and ytickrotate attributes.

In [9]:

_ = Heatmap(
    {
        "charts": {
            "data": [[x + y for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
            # add the x-axis ticks, labels and rotation
            "xticks": [idx for idx in range(8)],
            "xticklabels": [f"xxx{idx}" for idx in range(8)],
            "xtickrotate": 45,
            # add the y-axis ticks, labels and rotation
            "yticks": [idx for idx in range(8)],
            "yticklabels": [f"xxx{idx}" for idx in range(8)],
            "ytickrotate": 0,
        },
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.SQUARE_SMALL,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

_ = Heatmap( { "charts": { "data": [[x + y for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, # add the x-axis ticks, labels and rotation "xticks": [idx for idx in range(8)], "xticklabels": [f"xxx{idx}" for idx in range(8)], "xtickrotate": 45, # add the y-axis ticks, labels and rotation "yticks": [idx for idx in range(8)], "yticklabels": [f"xxx{idx}" for idx in range(8)], "ytickrotate": 0, }, "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.SQUARE_SMALL, "show_heatmap_values": True, "show_colorbars": True, } )

Heatmap style¶

To change a single heatmap style simply add the style attribute with the corresponding attributes. The supported attributes are shown in the datachart.typings.HeatmapStyleAttrs type, which contains the following attributes:

Attribute	Description
"plot_heatmap_cmap"	The colormap used to draw the heatmap.
"plot_heatmap_alpha"	The alpha of the heatmap (how visible the heatmap is).
"plot_heatmap_font_size"	The font size.
"plot_heatmap_font_color"	The font color.
"plot_heatmap_font_style"	The font style (normal, italic, etc.).
"plot_heatmap_font_weight"	The font weight (normal, bold, etc.).

Again, to help with the style settings, the datachart.constants module contains the following constants:

Constant	Description
datachart.constants.COLORS	The colormap used to draw the heatmap.
datachart.constants.FONT_STYLE	The font style (normal, italic, etc.).
datachart.constants.FONT_WEIGHT	The font weight (normal, bold, etc.).

In [10]:

from datachart.constants import COLORS, FONT_STYLE, FONT_WEIGHT

from datachart.constants import COLORS, FONT_STYLE, FONT_WEIGHT

In [11]:

_ = Heatmap(
    {
        "charts": {
            "data": [[x + y for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
            # define the style of the heatmap
            "style": {
                "plot_heatmap_cmap": COLORS.GnBu,
                "plot_heatmap_font_style": FONT_STYLE.ITALIC,
                "plot_heatmap_font_weight": FONT_WEIGHT.BOLD,
            }
        },
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.SQUARE_SMALL,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

_ = Heatmap( { "charts": { "data": [[x + y for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, # define the style of the heatmap "style": { "plot_heatmap_cmap": COLORS.GnBu, "plot_heatmap_font_style": FONT_STYLE.ITALIC, "plot_heatmap_font_weight": FONT_WEIGHT.BOLD, } }, "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.SQUARE_SMALL, "show_heatmap_values": True, "show_colorbars": True, } )

Heatmap normalization¶

To change how the heatmap colors is normalized, add the norm attribute inside the chart attribute. The possible options are:

Option	Description
None	No normalization.
"linear"	Linear normalization.
"log"	Log normalization.
"symlog"	Symlog normalization.
"asinh"	Asinh normalization.

Again, datachart provides a datachart.constants.NORMALIZE constant, which contains the supported options.

In [12]:

from datachart.constants import NORMALIZE

from datachart.constants import NORMALIZE

In [13]:

_ = Heatmap(
    {
        "charts": {
            "data": [[x + y for x in range(8)] for y in range(8)],
            # define the normalization
            "norm": NORMALIZE.LOG,
            "valfmt": VALFMT.DECIMAL,
            "style": {
                "plot_heatmap_cmap": COLORS.GnBu,
            }
        },
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.SQUARE_SMALL,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

_ = Heatmap( { "charts": { "data": [[x + y for x in range(8)] for y in range(8)], # define the normalization "norm": NORMALIZE.LOG, "valfmt": VALFMT.DECIMAL, "style": { "plot_heatmap_cmap": COLORS.GnBu, } }, "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.SQUARE_SMALL, "show_heatmap_values": True, "show_colorbars": True, } )

Multiple Heatmap Charts¶

To add multiple heatmaps charts, simply add the charts attribute with a list of charts, as shown below.

Attributes same as creating a single chart

We designed the datachart.charts.* functions to use the same attribute naming when possible. To create multiple charts, the charts attribute becomes a list of dictionaries with the same attributes as when creating a single chart.

In [14]:

_ = Heatmap(
    {
        # use a list of charts to define multiple heatmaps
        "charts": [{
            "data": [[x + y for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
            "style": {
                "plot_heatmap_cmap": COLORS.GnBu,
            }
        }, {
            "data": [[1 / (x + y + 1) for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
        }],
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.A4_REGULAR,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

_ = Heatmap( { # use a list of charts to define multiple heatmaps "charts": [{ "data": [[x + y for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, "style": { "plot_heatmap_cmap": COLORS.GnBu, } }, { "data": [[1 / (x + y + 1) for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, }], "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.A4_REGULAR, "show_heatmap_values": True, "show_colorbars": True, } )

Sub-chart subtitles¶

We can name each chart by adding the subtitle attribute to each chart.

In [15]:

figure = Heatmap(
    {
        "charts": [{
            "data": [[x + y for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
            "style": {
                "plot_heatmap_cmap": COLORS.GnBu,
            },
            # add a subtitle to the chart
            "subtitle": "Subtitle 1",
        }, {
            "data": [[1 / (x + y + 1) for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
            # add a subtitle to the chart
            "subtitle": "Subtitle 2",
        }],
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.A4_REGULAR,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

figure = Heatmap( { "charts": [{ "data": [[x + y for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, "style": { "plot_heatmap_cmap": COLORS.GnBu, }, # add a subtitle to the chart "subtitle": "Subtitle 1", }, { "data": [[1 / (x + y + 1) for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, # add a subtitle to the chart "subtitle": "Subtitle 2", }], "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.A4_REGULAR, "show_heatmap_values": True, "show_colorbars": True, } )

Saving the Chart as an Image¶

To save the chart as an image, use the datachart.utils.save_figure function.

In [16]:

from datachart.utils import save_figure

from datachart.utils import save_figure

In [17]:

save_figure(figure, "./fig_heatmap.png", dpi=300)

save_figure(figure, "./fig_heatmap.png", dpi=300)

The figure should be saved in the current working directory.

Example Use Cases¶

Example 1: Distance comparison¶

Under development

This example is still under development. If you are interested in improving it, please let us know.

The example below shows how to the heatmap showing the components of the pair-wise distance matrices.

In [18]:

_ = Heatmap(
    {
        "charts": [{
            "subtitle": "Subtitle 1",
            "data": [[x + y for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
            "style": {
                "plot_heatmap_cmap": COLORS.GnBu,
            }
        }, {
            "subtitle": "Subtitle 2",
            "data": [[10 / (x + y + 1) for x in range(8)] for y in range(8)],
            "valfmt": VALFMT.DECIMAL,
        }],
        "title": "Title",
        "xlabel": "the global x-axis label",
        "ylabel": "the global y-axis label",
        "figsize": FIG_SIZE.A4_REGULAR,
        "show_heatmap_values": True,
        "show_colorbars": True,
    }
)

_ = Heatmap( { "charts": [{ "subtitle": "Subtitle 1", "data": [[x + y for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, "style": { "plot_heatmap_cmap": COLORS.GnBu, } }, { "subtitle": "Subtitle 2", "data": [[10 / (x + y + 1) for x in range(8)] for y in range(8)], "valfmt": VALFMT.DECIMAL, }], "title": "Title", "xlabel": "the global x-axis label", "ylabel": "the global y-axis label", "figsize": FIG_SIZE.A4_REGULAR, "show_heatmap_values": True, "show_colorbars": True, } )