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 keyword arguments for chart configuration. The main argument is data, which contains the heatmap matrix. For a single heatmap, data is a 2D list. For multiple heatmaps, data is a list of 2D lists.

Heatmap(
    data=List[List[Union[int, float, None]]],               # The data of the chart (or list of 2D arrays for multiple)
    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 subtitle of the chart (or list for multiple charts)
    title=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[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[str]],                        # the y-axis tick labels (must be same length as yticks)
    ytickrotate=Optional[int],                              # the y-axis tick labels rotation

    colorbar={                                              # the colorbar configuration
        "orientation": Optional[ORIENTATION],               # the colorbar 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 data argument is required to draw the heatmap chart.

In [2]:

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

_ = Heatmap( # add the data to the chart 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(
    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( 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(
    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( 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(
    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( 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(
    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( 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(
    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( 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(
    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( 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 argument. 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(
    data=[[x + y for x in range(8)] for y in range(8)],
    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( data=[[x + y for x in range(8)] for y in range(8)], 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 create multiple heatmaps, pass a list of 2D arrays to the data argument. Each 2D array represents one heatmap. Per-chart attributes like subtitle, style, and valfmt can be passed as lists, where each element corresponds to a chart.

Multiple charts pattern

For multiple charts, data becomes a list of 2D arrays, and per-chart attributes like subtitle, style, and valfmt become lists where each element applies to the corresponding chart.

In [14]:

_ = Heatmap(
    # use a list of 2D arrays to define multiple heatmaps
    data=[
        [[x + y for x in range(8)] for y in range(8)],
        [[1 / (x + y + 1) for x in range(8)] for y in range(8)],
    ],
    valfmt=VALFMT.DECIMAL,
    style=[
        {"plot_heatmap_cmap": COLORS.GnBu},
        {},  # use default style for the second heatmap
    ],
    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 2D arrays to define multiple heatmaps data=[ [[x + y for x in range(8)] for y in range(8)], [[1 / (x + y + 1) for x in range(8)] for y in range(8)], ], valfmt=VALFMT.DECIMAL, style=[ {"plot_heatmap_cmap": COLORS.GnBu}, {}, # use default style for the second heatmap ], 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 passing a list of subtitles to the subtitle argument.

In [15]:

figure = Heatmap(
    data=[
        [[x + y for x in range(8)] for y in range(8)],
        [[1 / (x + y + 1) for x in range(8)] for y in range(8)],
    ],
    valfmt=VALFMT.DECIMAL,
    style=[
        {"plot_heatmap_cmap": COLORS.GnBu},
        None,
    ],
    # add a subtitle to each chart
    subtitle=["Subtitle 1", "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( data=[ [[x + y for x in range(8)] for y in range(8)], [[1 / (x + y + 1) for x in range(8)] for y in range(8)], ], valfmt=VALFMT.DECIMAL, style=[ {"plot_heatmap_cmap": COLORS.GnBu}, None, ], # add a subtitle to each chart subtitle=["Subtitle 1", "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(
    data=[
        [[x + y for x in range(8)] for y in range(8)],
        [[10 / (x + y + 1) for x in range(8)] for y in range(8)],
    ],
    subtitle=["Subtitle 1", "Subtitle 2"],
    valfmt=VALFMT.DECIMAL,
    style=[
        {"plot_heatmap_cmap": COLORS.GnBu},
        None,
    ],
    # add the x-axis ticks and labels
    xticks=[idx for idx in range(8)],
    xticklabels=[f"xx{idx}" for idx in range(8)],
    # add the y-axis ticks and labels
    yticks=[idx for idx in range(8)],
    yticklabels=[f"yy{idx}" for idx in range(8)],
    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( data=[ [[x + y for x in range(8)] for y in range(8)], [[10 / (x + y + 1) for x in range(8)] for y in range(8)], ], subtitle=["Subtitle 1", "Subtitle 2"], valfmt=VALFMT.DECIMAL, style=[ {"plot_heatmap_cmap": COLORS.GnBu}, None, ], # add the x-axis ticks and labels xticks=[idx for idx in range(8)], xticklabels=[f"xx{idx}" for idx in range(8)], # add the y-axis ticks and labels yticks=[idx for idx in range(8)], yticklabels=[f"yy{idx}" for idx in range(8)], 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, )