Major colorbar_wrapper cleanup, 1d and 2d plotting docs

Author: lukelbd

docs/1dplots.ipynb

@@ -30,14 +30,14 @@
    },
    "source": [
     "The `~proplot.wrappers.standardize_1d` wrapper used to standardize the input of a bunch of different plotting functions. \n",
-    "`~proplot.wrappers.standardize_1d` allows you to optionally omit *x* coordinates (in which case they are inferred from the *y* coordinates) or pass 2D *y* coordinate arrays (in which case the plotting method is called with each column of the array). See the documentation for details."
+    "`~proplot.wrappers.standardize_1d` allows you to optionally omit *x* coordinates (in which case they are inferred from the *y* coordinates) or pass 2D *y* coordinate arrays (in which case the plotting method is called with each column of the array)."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Pandas and xarray integration"
+    "## Pandas and xarray"
    ]
   },
   {
@@ -96,23 +96,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## On-the-fly property cycles"
-   ]
-  },
-  {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
-   "source": [
-    "The `~proplot.wrappers.cycle_changer` wrapper allows you to create and apply new property cyclers on-the-fly. Just pass the `cycle` keyword argument to any supported plotting method. See :ref:`Making new color cycles` for details."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Easier error bars"
+    "## On-the-fly error bars"
    ]
   },
   {
@@ -329,38 +313,40 @@
    "source": [
     "import proplot as plot\n",
     "import numpy as np\n",
-    "plot.rc.reset()\n",
     "N = 50\n",
     "cmap = 'IceFire'\n",
     "values = np.linspace(-N/2, N/2, N)\n",
     "f, axs = plot.subplots(share=0, ncols=2, wratios=(2, 1),\n",
     "                       axwidth='6cm', aspect=(2, 1))\n",
+    "axs.format(suptitle='Parametric plots demo')\n",
+    "# Smooth gradations\n",
     "ax = axs[0]\n",
     "state = np.random.RandomState(51423)\n",
     "m = ax.plot((state.rand(N) - 0.5).cumsum(), state.rand(N),\n",
     "            cmap=cmap, values=values, lw=7, extend='both')\n",
     "ax.format(xlabel='xlabel', ylabel='ylabel',\n",
-    "          title='Line with smooth color gradations', titleweight='bold')\n",
+    "          title='Line with smooth gradations')\n",
     "ax.format(xlim=(-1, 5), ylim=(-0.2, 1.2))\n",
     "ax.colorbar(m, loc='b', label='parametric coordinate', locator=5)\n",
+    "# Step gradations\n",
     "N = 12\n",
     "ax = axs[1]\n",
-    "values = np.linspace(-N/2, N/2 - 1, N)\n",
-    "radii = np.linspace(1, 0.2, N)\n",
-    "angles = np.linspace(0, 4*np.pi, N)\n",
+    "values = np.linspace(-N/2, N/2, N + 1)\n",
+    "radii = np.linspace(1, 0.2, N + 1)\n",
+    "angles = np.linspace(0, 4*np.pi, N + 1)\n",
     "x = radii*np.cos(1.4*angles)\n",
     "y = radii*np.sin(1.4*angles)\n",
     "m = ax.plot(x, y, values=values, linewidth=15, interp=False, cmap=cmap)\n",
     "ax.format(xlim=(-1, 1), ylim=(-1, 1), title='Step gradations',\n",
-    "          titleweight='bold', xlabel='cosine angle', ylabel='sine angle')\n",
+    "          xlabel='cosine angle', ylabel='sine angle')\n",
     "ax.colorbar(m, loc='b', maxn=10, label=f'parametric coordinate')"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Misc enhancements"
+    "## Scatter plots"
    ]
   },
   {
@@ -369,7 +355,7 @@
     "raw_mimetype": "text/restructuredtext"
    },
    "source": [
-    "Thanks to `~proplot.wrappers.scatter_wrapper` and `~proplot.wrappers.cycle_changer`, `~matplotlib.axes.Axes.scatter` now accepts 2D arrays, just like `~matplotlib.axes.Axes.plot`, and successive calls to `~matplotlib.axes.Axes.scatter` can apply property cycle keys other than `color` -- for example, `marker` and `markersize`. `~matplotlib.axes.Axes.scatter` also now optionally accepts keywords that look like the `~matplotlib.axes.Axes.plot` keywords, which is a bit less confusing. You can also pass colormaps to `~matplotlib.axes.Axes.scatter` just as with matplotlib.\n",
+    "Thanks to `~proplot.wrappers.scatter_wrapper` and `~proplot.wrappers.cycle_changer`, `~matplotlib.axes.Axes.scatter` now accepts 2D arrays, just like `~matplotlib.axes.Axes.plot`, and successive calls to `~matplotlib.axes.Axes.scatter` can apply property cycle keys other than `color` -- for example, `marker` and `markersize`. `~matplotlib.axes.Axes.scatter` also now optionally takes keywords that look like the `~matplotlib.axes.Axes.plot` keywords, which is a bit less confusing. You can also pass colormaps to `~matplotlib.axes.Axes.scatter` just as with matplotlib.\n",
     "\n",
     "We are also considering supporting 2D array input and property cycle iteration for more obscure matplotlib plotting commands like `~matplotlib.axes.Axes.stem`, `~matplotlib.axes.Axes.step`, `~matplotlib.axes.Axes.vlines`, and `~matplotlib.axes.Axes.hlines`. Stay tuned!"
    ]
@@ -395,10 +381,10 @@
     "                 cycle_kw={'marker': ['x', 'o', 'x', 'o'], 'markersize': [5, 10, 20, 30]})\n",
     "ax = axs[1]\n",
     "ax.format(title='Scatter plot with cmap')\n",
-    "data = (state.rand(2, 100) - 0.5)\n",
+    "data = state.rand(2, 100)\n",
     "obj = ax.scatter(*data, color=data.sum(axis=0), size=state.rand(100), smin=3, smax=30,\n",
-    "                 marker='o', cmap='dusk', colorbar='lr',\n",
-    "                 colorbar_kw={'locator': 0.5, 'label': 'label'})\n",
+    "                 marker='o', cmap='plum', colorbar='lr', vmin=0, vmax=2,\n",
+    "                 colorbar_kw={'label': 'label', 'locator':0.5})\n",
     "axs.format(xlabel='xlabel', ylabel='ylabel')"
    ]
   }

docs/2dplots.ipynb

@@ -30,14 +30,14 @@
    },
    "source": [
     "The `~proplot.wrappers.standardize_2d` wrapper is used to standardize the input of a bunch of different plotting functions. \n",
-    "It allows you to optionally omit *x* and *y* coordinates, in which case they are inffered from the data array; guesses graticule edges for `~matplotlib.axes.Axes.pcolor` and `~matplotlib.axes.Axes.pcolormesh` plots; and optionally enforces global data coverage when plotting in map projections. See the documentation for details."
+    "It allows you to optionally omit *x* and *y* coordinates, in which case they are inffered from the data array; guesses graticule edges for `~matplotlib.axes.Axes.pcolor` and `~matplotlib.axes.Axes.pcolormesh` plots; and optionally enforces global data coverage when plotting in map projections."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Pandas and xarray integration"
+    "## Pandas and xarray"
    ]
   },
   {
@@ -98,23 +98,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## On-the-fly colormaps"
-   ]
-  },
-  {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
-   "source": [
-    "The `~proplot.wrappers.cmap_changer` wrapper allows you to create and apply new colormaps on-the-fly.  Just pass the `cmap` keyword argument to any supported plotting method. See :ref:`Making new colormaps` for details. This wrapper also implements the features described in :ref:`Colormap levels`, :ref:`Colormap normalizers`, and :ref:`Pcolor and contour labels` below."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Colormap levels"
+    "## Discrete colormap levels"
    ]
   },
   {
@@ -141,12 +125,9 @@
     "state = np.random.RandomState(51423)\n",
     "data = (state.normal(0, 1, size=(33, 33))).cumsum(axis=0).cumsum(axis=1)\n",
     "axs.format(suptitle='Pcolor with levels demo')\n",
-    "ax = axs[0]\n",
-    "ax.pcolor(data, cmap=cmap, N=200, symmetric=True, colorbar='l')\n",
-    "ax.format(title='Ambiguous values', yformatter='null')\n",
-    "ax = axs[1]\n",
-    "ax.pcolor(data, cmap=cmap, N=10, symmetric=True, colorbar='r')\n",
-    "ax.format(title='Discernible levels')"
+    "for ax, n, mode, side in zip(axs, (200, 10), ('Ambiguous', 'Discernible'), 'lr'):\n",
+    "    ax.pcolor(data, cmap=cmap, N=n, symmetric=True, colorbar=side)\n",
+    "    ax.format(title=f'{mode} values', yformatter='null')"
    ]
   },
   {
@@ -179,8 +160,8 @@
     "data = (20*(state.rand(20, 20) - 0.4).cumsum(axis=0).cumsum(axis=1)) % 360\n",
     "# Show cyclic colorbar with distinct end colors\n",
     "ax = axs[0]\n",
-    "ax.pcolormesh(data, levels=levels, cmap='phase',\n",
-    "              extend='neither', colorbar='b')\n",
+    "ax.pcolormesh(data, levels=levels, cmap='phase', extend='neither',\n",
+    "              colorbar='b', colorbar_kw={'locator': 90})\n",
     "ax.format(title='cyclic colormap\\nwith distinct end colors')\n",
     "# Show colorbars with different extend values\n",
     "for ax, extend in zip(axs[1:], ('min', 'max', 'neither', 'both')):\n",
@@ -193,7 +174,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "##  Colormap normalizers"
+    "##  Colormap normalization"
    ]
   },
   {
@@ -202,7 +183,11 @@
     "raw_mimetype": "text/restructuredtext"
    },
    "source": [
-    "If you pass unevenly spaced `levels` to a plotting command, the `~proplot.styletools.LinearSegmentedNorm` normalizer is applied by default. This results in even color gradations across *indices* of the level list, no matter their spacing. To use an arbitrary colormap normalizer, just pass `norm` and optionally `norm_kw` to a command wrapped by `~proplot.wrappers.cmap_changer`. These arguments are passed to the `~proplot.styletools.Norm` constructor."
+    "If you pass unevenly spaced `levels` to a plotting command, the `~proplot.styletools.LinearSegmentedNorm` normalizer is applied by default. This results in even color gradations across *indices* of the level list, no matter their spacing. \n",
+    "\n",
+    "There is a new `~proplot.styletools.MidpointNorm` class that warps your colormap so that its midpoint lies on some central data value, no matter the minimum and maximum colormap colors.\n",
+    "\n",
+    "To use an arbitrary colormap normalizer, just pass `norm` and optionally `norm_kw` to a command wrapped by `~proplot.wrappers.cmap_changer`. These arguments are passed to the `~proplot.styletools.Norm` constructor."
    ]
   },
   {
@@ -213,6 +198,7 @@
    "source": [
     "import proplot as plot\n",
     "import numpy as np\n",
+    "# Linear segmented norm\n",
     "f, axs = plot.subplots(ncols=2, axwidth=2.5, aspect=1.5)\n",
     "state = np.random.RandomState(51423)\n",
     "data = 10**(2*state.rand(20, 20).cumsum(axis=0)/7)\n",
@@ -221,36 +207,17 @@
     "    m = axs[i].contourf(data, levels=ticks, extend='both',\n",
     "                        cmap='Mako', norm=norm, colorbar='b')\n",
     "    axs[i].format(title=title)\n",
-    "axs.format(suptitle='Level normalizers demo')"
-   ]
-  },
-  {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
-   "source": [
-    "Finally, there is a new `~proplot.styletools.MidpointNorm` class that warps your colormap so that its midpoint lies on some central data value, no matter the minimum and maximum colormap colors. Again, to use an arbitrary colormap normalizer, just pass `norm` and optionally `norm_kw` to a command wrapped by `~proplot.wrappers.cmap_changer`. These arguments are passed to the `~proplot.styletools.Norm` constructor."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import proplot as plot\n",
-    "import numpy as np\n",
-    "state = np.random.RandomState(51423)\n",
+    "axs.format(suptitle='Level normalizers demo')\n",
+    "# Midpoint norm\n",
     "data1 = (state.rand(20, 20) - 0.43).cumsum(axis=0)\n",
     "data2 = (state.rand(20, 20) - 0.57).cumsum(axis=0)\n",
     "f, axs = plot.subplots(ncols=2, axwidth=2.5, aspect=1.5)\n",
     "cmap = plot.Colormap('Moisture', cut=0.1)\n",
     "axs.format(suptitle='Midpoint normalizer demo')\n",
-    "axs[0].contourf(data1, norm='midpoint', cmap=cmap, colorbar='b')\n",
-    "axs[0].format(title='Skewed positive data')\n",
-    "axs[1].contourf(data2, norm='midpoint', cmap=cmap, colorbar='b')\n",
-    "axs[1].format(title='Skewed negative data')"
+    "for ax, data, mode in zip(axs, (data1, data2), ('positive', 'negative')):\n",
+    "    m = ax.contourf(data, norm='midpoint', cmap=cmap)\n",
+    "    ax.colorbar(m, loc='b', locator=1, minorlocator=0.25)\n",
+    "    ax.format(title=f'Skewed {mode} data')"
    ]
   },
   {
@@ -305,7 +272,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Heatmaps and covariance matrices"
+    "## Heatmap plots"
    ]
   },
   {

docs/colorbars_legends.ipynb

@@ -139,7 +139,7 @@
     "for abc, color in zip('ABCDEF', cycle):\n",
     "    h = axs[2:].plot(state.rand(10), lw=3, color=color, label=f'line {abc}')\n",
     "    hs.extend(h[0])\n",
-    "f.colorbar(m[0], length=0.8, label='colorbar label', loc='b', col=1)\n",
+    "f.colorbar(m[0], length=0.8, label='colorbar label', loc='b', col=1, locator=5)\n",
     "f.colorbar(m[0], label='colorbar label', loc='l')\n",
     "f.legend(hs, ncols=2, center=True, frame=False, loc='b', col=2)\n",
     "f.legend(hs, ncols=1, label='legend label', frame=False, loc='r')\n",

proplot/axes.py

@@ -2313,7 +2313,7 @@ class generated by `plot.CutoffScaleFactory('cutoff', 0.5, 2)`.
                                 raise ValueError(
                                     f'Invalid {x} spine location {spineloc!r}.'
                                     f' Options are '
-                                    ', '.join(map(
+                                    + ', '.join(map(
                                         repr, (*sides, 'both', 'neither')
                                     )) + '.'
                                 )

proplot/axistools.py

@@ -122,7 +122,7 @@ def Locator(locator, *args, **kwargs):
         if locator not in locators:
             raise ValueError(
                 f'Unknown locator {locator!r}. Options are '
-                ', '.join(map(repr, locators.keys())) + '.')
+                + ', '.join(map(repr, locators.keys())) + '.')
         locator = locators[locator](*args, **kwargs)
     elif isinstance(locator, Number):  # scalar variable
         locator = mticker.MultipleLocator(locator, *args, **kwargs)
@@ -256,7 +256,7 @@ def Formatter(formatter, *args, date=False, **kwargs):
             if formatter not in formatters:
                 raise ValueError(
                     f'Unknown formatter {formatter!r}. Options are '
-                    ', '.join(map(repr, formatters.keys())) + '.')
+                    + ', '.join(map(repr, formatters.keys())) + '.')
             formatter = formatters[formatter](*args, **kwargs)
     elif callable(formatter):
         formatter = mticker.FuncFormatter(formatter, *args, **kwargs)
@@ -337,7 +337,7 @@ def Scale(scale, *args, **kwargs):
     else:
         raise ValueError(
             f'Unknown scale or preset {scale!r}. Options are '
-            ', '.join(map(repr, list(scales) + list(SCALE_PRESETS))) + '.')
+            + ', '.join(map(repr, list(scales) + list(SCALE_PRESETS))) + '.')
     axis = _dummy_axis()
     return scale(axis, *args, **kwargs)
 
@@ -518,7 +518,7 @@ def _scale_factory(scale, axis, *args, **kwargs):
         if scale not in scales:
             raise ValueError(
                 f'Unknown scale {scale!r}. Options are '
-                ', '.join(map(repr, scales.keys())) + '.')
+                + ', '.join(map(repr, scales.keys())) + '.')
         return scales[scale](axis, *args, **kwargs)
 
 

proplot/projs.py

@@ -160,8 +160,8 @@ def Proj(name, basemap=False, **kwargs):
                 'for cartopy axes.')
         if crs is None:
             raise ValueError(
-                f'Unknown projection "{name}". Options are: '
-                ', '.join(map(repr, cartopy_projs.keys())))
+                f'Unknown projection {name!r}. Options are: '
+                + ', '.join(map(repr, cartopy_projs.keys())))
         proj = crs(**kwargs)
         aspect = (np.diff(proj.x_limits) / np.diff(proj.y_limits))[0]
     return proj, aspect