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:
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.
_ = 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.
_ = 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.
from datachart.constants import FIG_SIZE
_ = 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.
_ = 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. |
from datachart.constants import VALFMT
_ = 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.
_ = 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.). |
from datachart.constants import COLORS, FONT_STYLE, FONT_WEIGHT
_ = 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.
from datachart.constants import NORMALIZE
_ = 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.
_ = 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.
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.
from datachart.utils import save_figure
save_figure(figure, "./fig_heatmap.png", dpi=300)
The figure should be saved in the current working directory.
_ = 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,
}
)