{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n# Annotated heatmap\n\nIt is often desirable to show data which depends on two independent\nvariables as a color coded image plot. This is often referred to as a\nheatmap. If the data is categorical, this would be called a categorical\nheatmap.\n\nMatplotlib's `~matplotlib.axes.Axes.imshow` function makes\nproduction of such plots particularly easy.\n\nThe following examples show how to create a heatmap with annotations.\nWe will start with an easy example and expand it to be usable as a\nuniversal function.\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## A simple categorical heatmap\n\nWe may start by defining some data. What we need is a 2D list or array\nwhich defines the data to color code. We then also need two lists or arrays\nof categories; of course the number of elements in those lists\nneed to match the data along the respective axes.\nThe heatmap itself is an `~matplotlib.axes.Axes.imshow` plot\nwith the labels set to the categories we have.\nNote that it is important to set both, the tick locations\n(`~matplotlib.axes.Axes.set_xticks`) as well as the\ntick labels (`~matplotlib.axes.Axes.set_xticklabels`),\notherwise they would become out of sync. The locations are just\nthe ascending integer numbers, while the ticklabels are the labels to show.\nFinally, we can label the data itself by creating a `~matplotlib.text.Text`\nwithin each cell showing the value of that cell.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import matplotlib.pyplot as plt\nimport numpy as np\n\nimport matplotlib\nimport matplotlib as mpl\n\n\nvegetables = [\"cucumber\", \"tomato\", \"lettuce\", \"asparagus\",\n \"potato\", \"wheat\", \"barley\"]\nfarmers = [\"Farmer Joe\", \"Upland Bros.\", \"Smith Gardening\",\n \"Agrifun\", \"Organiculture\", \"BioGoods Ltd.\", \"Cornylee Corp.\"]\n\nharvest = np.array([[0.8, 2.4, 2.5, 3.9, 0.0, 4.0, 0.0],\n [2.4, 0.0, 4.0, 1.0, 2.7, 0.0, 0.0],\n [1.1, 2.4, 0.8, 4.3, 1.9, 4.4, 0.0],\n [0.6, 0.0, 0.3, 0.0, 3.1, 0.0, 0.0],\n [0.7, 1.7, 0.6, 2.6, 2.2, 6.2, 0.0],\n [1.3, 1.2, 0.0, 0.0, 0.0, 3.2, 5.1],\n [0.1, 2.0, 0.0, 1.4, 0.0, 1.9, 6.3]])\n\n\nfig, ax = plt.subplots()\nim = ax.imshow(harvest)\n\n# Show all ticks and label them with the respective list entries\nax.set_xticks(range(len(farmers)), labels=farmers,\n rotation=45, ha=\"right\", rotation_mode=\"anchor\")\nax.set_yticks(range(len(vegetables)), labels=vegetables)\n\n# Loop over data dimensions and create text annotations.\nfor i in range(len(vegetables)):\n for j in range(len(farmers)):\n text = ax.text(j, i, harvest[i, j],\n ha=\"center\", va=\"center\", color=\"w\")\n\nax.set_title(\"Harvest of local farmers (in tons/year)\")\nfig.tight_layout()\nplt.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Using the helper function code style\n\nAs discussed in the `Coding styles `\none might want to reuse such code to create some kind of heatmap\nfor different input data and/or on different axes.\nWe create a function that takes the data and the row and column labels as\ninput, and allows arguments that are used to customize the plot\n\nHere, in addition to the above we also want to create a colorbar and\nposition the labels above of the heatmap instead of below it.\nThe annotations shall get different colors depending on a threshold\nfor better contrast against the pixel color.\nFinally, we turn the surrounding axes spines off and create\na grid of white lines to separate the cells.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "def heatmap(data, row_labels, col_labels, ax=None,\n cbar_kw=None, cbarlabel=\"\", **kwargs):\n \"\"\"\n Create a heatmap from a numpy array and two lists of labels.\n\n Parameters\n ----------\n data\n A 2D numpy array of shape (M, N).\n row_labels\n A list or array of length M with the labels for the rows.\n col_labels\n A list or array of length N with the labels for the columns.\n ax\n A `matplotlib.axes.Axes` instance to which the heatmap is plotted. If\n not provided, use current Axes or create a new one. Optional.\n cbar_kw\n A dictionary with arguments to `matplotlib.Figure.colorbar`. Optional.\n cbarlabel\n The label for the colorbar. Optional.\n **kwargs\n All other arguments are forwarded to `imshow`.\n \"\"\"\n\n if ax is None:\n ax = plt.gca()\n\n if cbar_kw is None:\n cbar_kw = {}\n\n # Plot the heatmap\n im = ax.imshow(data, **kwargs)\n\n # Create colorbar\n cbar = ax.figure.colorbar(im, ax=ax, **cbar_kw)\n cbar.ax.set_ylabel(cbarlabel, rotation=-90, va=\"bottom\")\n\n # Show all ticks and label them with the respective list entries.\n ax.set_xticks(range(data.shape[1]), labels=col_labels,\n rotation=-30, ha=\"right\", rotation_mode=\"anchor\")\n ax.set_yticks(range(data.shape[0]), labels=row_labels)\n\n # Let the horizontal axes labeling appear on top.\n ax.tick_params(top=True, bottom=False,\n labeltop=True, labelbottom=False)\n\n # Turn spines off and create white grid.\n ax.spines[:].set_visible(False)\n\n ax.set_xticks(np.arange(data.shape[1]+1)-.5, minor=True)\n ax.set_yticks(np.arange(data.shape[0]+1)-.5, minor=True)\n ax.grid(which=\"minor\", color=\"w\", linestyle='-', linewidth=3)\n ax.tick_params(which=\"minor\", bottom=False, left=False)\n\n return im, cbar\n\n\ndef annotate_heatmap(im, data=None, valfmt=\"{x:.2f}\",\n textcolors=(\"black\", \"white\"),\n threshold=None, **textkw):\n \"\"\"\n A function to annotate a heatmap.\n\n Parameters\n ----------\n im\n The AxesImage to be labeled.\n data\n Data used to annotate. If None, the image's data is used. Optional.\n valfmt\n The format of the annotations inside the heatmap. This should either\n use the string format method, e.g. \"$ {x:.2f}\", or be a\n `matplotlib.ticker.Formatter`. Optional.\n textcolors\n A pair of colors. The first is used for values below a threshold,\n the second for those above. Optional.\n threshold\n Value in data units according to which the colors from textcolors are\n applied. If None (the default) uses the middle of the colormap as\n separation. Optional.\n **kwargs\n All other arguments are forwarded to each call to `text` used to create\n the text labels.\n \"\"\"\n\n if not isinstance(data, (list, np.ndarray)):\n data = im.get_array()\n\n # Normalize the threshold to the images color range.\n if threshold is not None:\n threshold = im.norm(threshold)\n else:\n threshold = im.norm(data.max())/2.\n\n # Set default alignment to center, but allow it to be\n # overwritten by textkw.\n kw = dict(horizontalalignment=\"center\",\n verticalalignment=\"center\")\n kw.update(textkw)\n\n # Get the formatter in case a string is supplied\n if isinstance(valfmt, str):\n valfmt = matplotlib.ticker.StrMethodFormatter(valfmt)\n\n # Loop over the data and create a `Text` for each \"pixel\".\n # Change the text's color depending on the data.\n texts = []\n for i in range(data.shape[0]):\n for j in range(data.shape[1]):\n kw.update(color=textcolors[int(im.norm(data[i, j]) > threshold)])\n text = im.axes.text(j, i, valfmt(data[i, j], None), **kw)\n texts.append(text)\n\n return texts" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The above now allows us to keep the actual plot creation pretty compact.\n\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, ax = plt.subplots()\n\nim, cbar = heatmap(harvest, vegetables, farmers, ax=ax,\n cmap=\"YlGn\", cbarlabel=\"harvest [t/year]\")\ntexts = annotate_heatmap(im, valfmt=\"{x:.1f} t\")\n\nfig.tight_layout()\nplt.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Some more complex heatmap examples\n\nIn the following we show the versatility of the previously created\nfunctions by applying it in different cases and using different arguments.\n\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "np.random.seed(19680801)\n\nfig, ((ax, ax2), (ax3, ax4)) = plt.subplots(2, 2, figsize=(8, 6))\n\n# Replicate the above example with a different font size and colormap.\n\nim, _ = heatmap(harvest, vegetables, farmers, ax=ax,\n cmap=\"Wistia\", cbarlabel=\"harvest [t/year]\")\nannotate_heatmap(im, valfmt=\"{x:.1f}\", size=7)\n\n# Create some new data, give further arguments to imshow (vmin),\n# use an integer format on the annotations and provide some colors.\n\ndata = np.random.randint(2, 100, size=(7, 7))\ny = [f\"Book {i}\" for i in range(1, 8)]\nx = [f\"Store {i}\" for i in list(\"ABCDEFG\")]\nim, _ = heatmap(data, y, x, ax=ax2, vmin=0,\n cmap=\"magma_r\", cbarlabel=\"weekly sold copies\")\nannotate_heatmap(im, valfmt=\"{x:d}\", size=7, threshold=20,\n textcolors=(\"red\", \"white\"))\n\n# Sometimes even the data itself is categorical. Here we use a\n# `matplotlib.colors.BoundaryNorm` to get the data into classes\n# and use this to colorize the plot, but also to obtain the class\n# labels from an array of classes.\n\ndata = np.random.randn(6, 6)\ny = [f\"Prod. {i}\" for i in range(10, 70, 10)]\nx = [f\"Cycle {i}\" for i in range(1, 7)]\n\nqrates = list(\"ABCDEFG\")\nnorm = matplotlib.colors.BoundaryNorm(np.linspace(-3.5, 3.5, 8), 7)\nfmt = matplotlib.ticker.FuncFormatter(lambda x, pos: qrates[::-1][norm(x)])\n\nim, _ = heatmap(data, y, x, ax=ax3,\n cmap=mpl.colormaps[\"PiYG\"].resampled(7), norm=norm,\n cbar_kw=dict(ticks=np.arange(-3, 4), format=fmt),\n cbarlabel=\"Quality Rating\")\n\nannotate_heatmap(im, valfmt=fmt, size=9, fontweight=\"bold\", threshold=-1,\n textcolors=(\"red\", \"black\"))\n\n# We can nicely plot a correlation matrix. Since this is bound by -1 and 1,\n# we use those as vmin and vmax. We may also remove leading zeros and hide\n# the diagonal elements (which are all 1) by using a\n# `matplotlib.ticker.FuncFormatter`.\n\ncorr_matrix = np.corrcoef(harvest)\nim, _ = heatmap(corr_matrix, vegetables, vegetables, ax=ax4,\n cmap=\"PuOr\", vmin=-1, vmax=1,\n cbarlabel=\"correlation coeff.\")\n\n\ndef func(x, pos):\n return f\"{x:.2f}\".replace(\"0.\", \".\").replace(\"1.00\", \"\")\n\nannotate_heatmap(im, valfmt=matplotlib.ticker.FuncFormatter(func), size=7)\n\n\nplt.tight_layout()\nplt.show()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ ".. admonition:: References\n\n The use of the following functions, methods, classes and modules is shown\n in this example:\n\n - `matplotlib.axes.Axes.imshow` / `matplotlib.pyplot.imshow`\n - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`\n\n" ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.13.2" } }, "nbformat": 4, "nbformat_minor": 0 }