{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "\n.. redirect-from:: /tutorials/colors/colorbar_only\n\n# Customized Colorbars Tutorial\n\nThis tutorial shows how to build and customize standalone colorbars, i.e.\nwithout an attached plot.\n\nA `~.Figure.colorbar` needs a \"mappable\" (`matplotlib.cm.ScalarMappable`)\nobject (typically, an image) which indicates the colormap and the norm to be\nused. In order to create a colorbar without an attached image, one can instead\nuse a `.ScalarMappable` with no associated data.\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "import matplotlib.pyplot as plt\nimport matplotlib as mpl" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Basic continuous colorbar\nHere, we create a basic continuous colorbar with ticks and labels.\n\nThe arguments to the `~.Figure.colorbar` call are the `.ScalarMappable`\n(constructed using the *norm* and *cmap* arguments), the axes where the\ncolorbar should be drawn, and the colorbar's orientation.\n\nFor more information see the `~matplotlib.colorbar` API.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')\n\ncmap = mpl.cm.cool\nnorm = mpl.colors.Normalize(vmin=5, vmax=10)\n\nfig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap=cmap),\n cax=ax, orientation='horizontal', label='Some Units')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Colorbar attached next to a pre-existing axes\nAll examples in this tutorial (except this one) show a standalone colorbar on\nits own figure, but it is possible to display the colorbar *next* to a\npre-existing Axes *ax* by passing ``ax=ax`` to the colorbar() call (meaning\n\"draw the colorbar next to *ax*\") rather than ``cax=ax`` (meaning \"draw the\ncolorbar on *ax*\").\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, ax = plt.subplots(layout='constrained')\n\nfig.colorbar(mpl.cm.ScalarMappable(norm=mpl.colors.Normalize(0, 1), cmap='magma'),\n ax=ax, orientation='vertical', label='a colorbar label')" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Discrete and extended colorbar with continuous colorscale\nThe following example shows how to make a discrete colorbar based on a\ncontinuous cmap. We use `matplotlib.colors.BoundaryNorm` to describe the\ninterval boundaries (which must be in increasing order), and further pass the\n*extend* argument to it to further display \"over\" and \"under\" colors (which\nare used for data outside of the norm range).\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')\n\ncmap = mpl.cm.viridis\nbounds = [-1, 2, 5, 7, 12, 15]\nnorm = mpl.colors.BoundaryNorm(bounds, cmap.N, extend='both')\n\nfig.colorbar(mpl.cm.ScalarMappable(norm=norm, cmap=cmap),\n cax=ax, orientation='horizontal',\n label=\"Discrete intervals with extend='both' keyword\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Colorbar with arbitrary colors\nThe following example still uses a `.BoundaryNorm` to describe discrete\ninterval boundaries, but now uses a `matplotlib.colors.ListedColormap` to\nassociate each interval with an arbitrary color (there must be as many\nintervals than there are colors). The \"over\" and \"under\" colors are set on\nthe colormap using `.Colormap.with_extremes`.\n\nWe also pass additional arguments to `~.Figure.colorbar`:\n\n- To display the out-of-range values on the colorbar, we use the *extend*\n argument in the colorbar() call. (This is equivalent to passing the\n *extend* argument in the `.BoundaryNorm` constructor as done in the\n previous example.)\n- To make the length of each colorbar segment proportional to its\n corresponding interval, we use the *spacing* argument in the colorbar()\n call.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')\n\ncmap = (mpl.colors.ListedColormap(['red', 'green', 'blue', 'cyan'])\n .with_extremes(under='yellow', over='magenta'))\nbounds = [1, 2, 4, 7, 8]\nnorm = mpl.colors.BoundaryNorm(bounds, cmap.N)\n\nfig.colorbar(\n mpl.cm.ScalarMappable(cmap=cmap, norm=norm),\n cax=ax, orientation='horizontal',\n extend='both',\n spacing='proportional',\n label='Discrete intervals, some other units',\n)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Colorbar with custom extension lengths\nWe can customize the length colorbar extensions, on a colorbar with discrete\nintervals. To make the length of each extension the\nsame as the length of the interior colors, use ``extendfrac='auto'``.\n\n" ] }, { "cell_type": "code", "execution_count": null, "metadata": { "collapsed": false }, "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(6, 1), layout='constrained')\n\ncmap = (mpl.colors.ListedColormap(['royalblue', 'cyan', 'yellow', 'orange'])\n .with_extremes(over='red', under='blue'))\nbounds = [-1.0, -0.5, 0.0, 0.5, 1.0]\nnorm = mpl.colors.BoundaryNorm(bounds, cmap.N)\n\nfig.colorbar(\n mpl.cm.ScalarMappable(cmap=cmap, norm=norm),\n cax=ax, orientation='horizontal',\n extend='both', extendfrac='auto',\n spacing='uniform',\n label='Custom extension lengths, some other units',\n)\n\nplt.show()" ] } ], "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.5" } }, "nbformat": 4, "nbformat_minor": 0 }