René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[Doc]: Improving the pcolor(mesh) documentation: how NOT TO plot some data","articleBody":"### Documentation Link\n\nhttps://matplotlib.org/stable/gallery/images_contours_and_fields/pcolormesh_levels.html\n\n### Problem\n\n[ _The following can possibly also apply to pcolor or similar graphics_ ]\r\n\r\n`pcolormesh` is very useful when you need to **look precisely at the values of a 2D data field** (rather than using `contour` and `contourf` and wondering how the contours are computed):\r\n- If you want to pinpoint the **locations of specific values**, you need to use only a few specific colors, using `ListedColormap`.\r\n- And if you want to look at the **locations of only one value** (e.g. the location of a data mask), you need to plot only the values in **one** interval and **completely ignore the other values**\r\n\r\nThe [pcolormesh example page](https://matplotlib.org/stable/gallery/images_contours_and_fields/pcolormesh_levels.html) unfortunately does not cover the use cases mentioned above:\r\n- no example using `ListedColormap`\r\n- no mention that the **data will be plotted even if it lies outside the requested levels**, using the first and last specified colors! This is so misleading that it's almost more a bug than a feature! This is probably obvious for the matplotlib colormaps and norm gurus, but not for most people. I end up having to read again all the color documentation each time I come back to matplotlib\r\n- no mention that you have to explicitly **specify a transparent (`alpha=0`) color** using `set_bad`, `set_over` and `set_under` for **removing what should not be plotted**. Maybe there is a cleaner (more obvious) way to do that. I will be glad to learn that (from an improved documentation)\r\n- no mention that a workaround is to use `numpy.ma` to **mask the values that should not be plotted**. But this may be tricky for people who are not used to dealing with cleanly masked/missing values\n\n### Suggested improvement\n\nThe following code and output image, based on the [Making levels using Norms](https://matplotlib.org/stable/gallery/images_contours_and_fields/pcolormesh_levels.html#making-levels-using-norms) example tentatively shows what is missing (in my opinion) in the documentation, as described above\r\n\r\nIt can hopefully be used to improve/extend the documentation\r\n```\r\n#!/usr/bin/env python\r\n\r\n# pcolormesh test/example adapted from\r\n# https://matplotlib.org/stable/gallery/images_contours_and_fields/pcolormesh_levels.html#making-levels-using-norms\r\n\r\nimport matplotlib.pyplot as plt\r\nfrom matplotlib.colors import ListedColormap, BoundaryNorm\r\nfrom matplotlib.ticker import MaxNLocator\r\nimport numpy as np\r\n\r\n# make these smaller to increase the resolution\r\ndx, dy = 0.05, 0.05\r\n\r\n# generate 2 2d grids for the x \u0026 y bounds\r\ny, x = np.mgrid[slice(1, 5 + dy, dy),\r\n                slice(1, 5 + dx, dx)]\r\n\r\nz = np.sin(x)**10 + np.cos(10 + y*x) * np.cos(x)\r\n\r\n# x and y are bounds, so z should be the value *inside* those bounds.\r\n# Therefore, remove the last value from the z array.\r\nz = z[:-1, :-1]\r\n\r\n\r\n# pick the desired colormap, sensible levels, and define a normalization\r\n# instance which takes data values and translates those into levels.\r\ncmap_0 = plt.get_cmap('PiYG')\r\nlevels_0 = MaxNLocator(nbins=15).tick_values(z.min(), z.max())\r\nnorm_0 = BoundaryNorm(levels_0, ncolors=cmap_0.N, clip=True)\r\n\r\nfig, (ax_0, ax_1, ax_2, ax_3, ax_4, ax_5) = plt.subplots(nrows=6)\r\nfig.set_size_inches(5, 12)\r\n\r\nim_0 = ax_0.pcolormesh(x, y, z, cmap=cmap_0, norm=norm_0)\r\nfig.colorbar(im_0, ax=ax_0)\r\nax_0.set_title('pcolormesh with levels')\r\n\r\n\r\nax_1.set_title('3 intervals/colors covering the\\nfull data range ([%.3f, %.3f])' % (z.min(), z.max()))\r\n\r\ncmap_1 = ListedColormap(['pink', 'lavender', 'green'])\r\nlevels_1 = [-1.1, -0.3, 0.3, 1.1]\r\nnorm_1 = BoundaryNorm(levels_1, cmap_1.N)\r\n\r\nim_1 = ax_1.pcolormesh(x, y, z,\r\n                       cmap=cmap_1, norm=norm_1,\r\n                       zorder=20)\r\nfig.colorbar(im_1, ax=ax_1)\r\n\r\n\r\nax_2.set_title('Top of data range is above the color scale\\n...but set_over color is NOT specified')\r\n\r\ncmap_2 = ListedColormap(['pink', 'lavender'])\r\nlevels_2 = [-1.1, -0.3, 0.3]\r\nnorm_2 = BoundaryNorm(levels_2, cmap_2.N)\r\n\r\nim_2 = ax_2.pcolormesh(x, y, z,\r\n                       cmap=cmap_2, norm=norm_2,\r\n                     zorder=20)\r\nfig.colorbar(im_2, ax=ax_2)\r\n\r\n\r\nax_3.set_title('BLUE color specified for\\ndata ABOVE the color scale')\r\n\r\ncmap_3 = ListedColormap(['pink', 'lavender'])\r\ncmap_3.set_over('blue')\r\nlevels_3 = [-1.1, -0.3, 0.3]\r\nnorm_3 = BoundaryNorm(levels_3, cmap_3.N)\r\n\r\nim_3 = ax_3.pcolormesh(x, y, z,\r\n                       cmap=cmap_3, norm=norm_3,\r\n                       zorder=20)\r\ntext_3 = ax_3.text(0.05, 0.3, 'Test text\\nin the BACKGROUND',\r\n                   fontsize='xx-large',\r\n                   horizontalalignment='left',\r\n                   verticalalignment='center', transform=ax_3.transAxes,\r\n                   zorder=10)\r\nfig.colorbar(im_3, ax=ax_3)\r\n\r\n\r\nax_4.set_title('Color above the scale is now\\nfully TRANSPARENT (alpha=0)')\r\n\r\ncmap_4 = ListedColormap(['pink', 'lavender'])\r\ncmap_4.set_over('black', alpha=0)\r\nlevels_4 = [-1.1, -0.3, 0.3]\r\nnorm_4 = BoundaryNorm(levels_4, cmap_4.N)\r\n\r\nim_4 = ax_4.pcolormesh(x, y, z,\r\n                       cmap=cmap_4, norm=norm_4,\r\n                       zorder=20)\r\ntext_4 = ax_4.text(0.05, 0.3, 'Test text\\nin the BACKGROUND',\r\n                   fontsize='xx-large',\r\n                   horizontalalignment='left',\r\n                   verticalalignment='center', transform=ax_4.transAxes,\r\n                   zorder=10)\r\nfig.colorbar(im_4, ax=ax_4)\r\n\r\n\r\nax_5.set_title('Color above the scale is NOT TRANSPARENT\\n...but the data above 0. is MASKED')\r\n\r\n# MASK the values we do not want, instead of plotting them with a\r\n# fully transparent color\r\nzm = np.ma.masked_greater(z, 0.)\r\n\r\ncmap_5 = ListedColormap(['pink', 'lavender'])\r\n# For testing purpose, we explicitly specify a fully opaque color\r\n# (but opaque is the default anyway)\r\ncmap_5.set_over('black', alpha=1)\r\nlevels_5 = [-1.1, -0.3, 0.3]\r\nnorm_5 = BoundaryNorm(levels_5, cmap_5.N)\r\n\r\nim_5 = ax_5.pcolormesh(x, y, zm,\r\n                       cmap=cmap_5, norm=norm_5,\r\n                       zorder=20)\r\ntext_5 = ax_5.text(0.05, 0.3, 'Test text\\nin the BACKGROUND',\r\n                   fontsize='xx-large',\r\n                   horizontalalignment='left',\r\n                   verticalalignment='center', transform=ax_5.transAxes,\r\n                   zorder=10)\r\nfig.colorbar(im_5, ax=ax_5)\r\n\r\n\r\n# adjust spacing between subplots so `ax1` title and `ax0` tick labels\r\n# don't overlap\r\nfig.tight_layout()\r\n\r\nfig.savefig('test_pcolormesh.png')\r\n\r\nplt.show()\r\n```\r\n![test_pcolormesh](https://user-images.githubusercontent.com/2785573/132951175-5314bd0b-5e85-4b70-8355-52ccbd300987.png)\r\n\n\n### Matplotlib Version\n\n3.3.4\n\n### Matplotlib documentation version\n\n3.4.3","author":{"url":"https://github.com/jypeter","@type":"Person","name":"jypeter"},"datePublished":"2021-09-11T14:37:22.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":2},"url":"https://github.com/21043/matplotlib/issues/21043"}