Clarifying how shared colorbars are created

core/matplotlib/annotations-colorbars-layouts.ipynb

@@ -426,11 +426,54 @@
    "id": "1662bf3c",
    "metadata": {},
    "source": [
-    "You may have noticed the input argument `hist1[3]` to `fig.colorbar`. To clarify, `hist1` is a tuple returned by `hist2d`, and `hist1[3]` returns a `matplotlib.collections.QuadMesh` that points to the colormap. \n",
-    "\n",
+    "You may have noticed the input argument `hist1[3]` to `fig.colorbar`. To clarify, `hist1` is a tuple returned by `hist2d`, and `hist1[3]` returns a `matplotlib.collections.QuadMesh` that points to the colormap for the first histogram. To make sure that both histograms are using the same colormap with the same range of values, `vmax` is set to 0.18 for both plots. This ensures that both histograms are using colormaps that represent values from 0 (the default for histograms) to 0.18. Because the same data is used for both plots, it doesn't matter whether we pass in `hist1[3]` or `hist2[3]` to `fig.colorbar`.\n",
     "Read more at the [`matplotlib.axes.Axes.hist2d` documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.hist2d.html)."
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "84c50862",
+   "metadata": {},
+   "source": [
+    "Other kinds of plots can share colorbars too. A common use case is filled contour plots with shared colorbars for comparing data. `vmin` and `vmax` behave the same way for `contourf` as they do for `hist2d`. A downside to using the `vmin` and `vmax` kwargs when plotting two different datasets is that while the colormaps may be the same, the dataset with a smaller range of values won't show the full range of colors as seen below. Thus, it *does* matter in this particular example which output from `contourf` is used to make the colorbar."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "28d4cea3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "x2 = y2 = np.arange(-3, 3.01, 0.025)\n",
+    "X2, Y2 = np.meshgrid(x2, y2)\n",
+    "Z = np.sqrt(np.sin(X2) ** 2 + np.sin(Y2) ** 2)\n",
+    "Z2 = np.sqrt(2 * np.cos(X2) ** 2 + 2 * np.cos(Y2) ** 2)\n",
+    "\n",
+    "fig, ax = plt.subplots(nrows=1, ncols=2, constrained_layout=True)\n",
+    "c1 = ax[0].contourf(X2, Y2, Z, vmin=0, vmax=2)\n",
+    "c2 = ax[1].contourf(X2, Y2, Z2, vmin=0, vmax=2)\n",
+    "fig.colorbar(c1, ax=ax[0], location='bottom')\n",
+    "fig.colorbar(c2, ax=ax[1], location='bottom')\n",
+    "\n",
+    "fig.suptitle('Shared colormaps on data with different ranges')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5570ebb7",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(nrows=1, ncols=2, constrained_layout=True)\n",
+    "c1 = ax[0].contourf(X2, Y2, Z, vmin=0, vmax=2)\n",
+    "c2 = ax[1].contourf(X2, Y2, Z2, vmin=0, vmax=2)\n",
+    "fig.colorbar(c2, ax=ax, location='bottom')\n",
+    "\n",
+    "fig.suptitle('Using the contourf output from the data with a wider range')"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "92d072f8-7370-4ea5-92e0-4407cb5905bb",
@@ -495,6 +538,17 @@
     "cbar = fig.colorbar(hist1[3], ax=ax, location='bottom')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "ea7f200f",
+   "metadata": {},
+   "source": [
+    "### The `Normalize` Class\n",
+    "Note that both plots use the `norm` kwarg. The `Normalize` class linearly normalizes data into the [0, 1] interval. This is used to linearly map the colors in the colormap to the data from `vmin` to `vmax`. In fact, we used this functionality in the previous histogram exercise! The `vmin` and `vmax` kwargs for `hist2d` are simply passed into the `Normalize` function. When making a custom colormap, it is best to specify how you want the data normalized.\n",
+    "\n",
+    "For non-linear nomalization, check out this [Colormap Normalization tutorial](https://matplotlib.org/stable/tutorials/colors/colormapnorms.html#)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "e41f44e0-2c4f-4ce2-abe6-35d20b8c142e",
@@ -628,7 +682,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.10.5"
   }
  },
  "nbformat": 4,