Merge pull request #162 from lukelbd/scatter-discrete-norm

Support DiscreteNorm in scatter plot colorbars

Author: lukelbd

.pre-commit-config.yaml

@@ -10,4 +10,4 @@ repos:
     - id: end-of-file-fixer
     - id: trailing-whitespace
     - id: flake8
-      args: ['--max-line-length=88', '--ignore=W503,E402']
+      args: ['--max-line-length=88', '--ignore=W503,E402,E741']

.travis.yml

@@ -38,7 +38,7 @@ install:
   - which python
 
 script:
-  - flake8 proplot docs --max-line-length=88 --ignore=W503,E402
+  - flake8 proplot docs --max-line-length=88 --ignore=W503,E402,E741
   - pushd docs
   - make html
   - popd

CHANGELOG.rst

@@ -115,6 +115,8 @@ There are quite a lot of deprecations for this release.
 
 .. rubric:: Features
 
+- Support building a colormap and `DiscreteNorm` inside `~matplotlib.axes.Axes.scatter`,
+  just like `contourf` and `pcolormesh` (:pr:`162`).
 - Support `cartopy 0.18 <https://scitools.org.uk/cartopy/docs/latest/whats_new.html>`__
   locators, formatters, deprecations, and new labelling features (:pr:`158`).
 - Add :rcraw:`geogrid.labelpad` and :rcraw:`geogrid.rotatelabels` settings

docs/1dplots.py

@@ -40,7 +40,7 @@
 # It is often desirable to use different `property cycles
 # <https://matplotlib.org/tutorials/intermediate/color_cycle.html#sphx-glr-tutorials-intermediate-color-cycle-py>`__
 # for different axes or different plot elements. To enable this, the
-# `~proplot.wrappers.cycle_changer` adds the `cycle` and `cycle_kw` to the 1D
+# `~proplot.axes.cycle_changer` adds the `cycle` and `cycle_kw` to the 1D
 # plotting methods. These arguments are passed to the
 # `~proplot.constructor.Cycle` constructor function, and the resulting property
 # cycle is used to style the input data. ProPlot iterates through property
@@ -76,9 +76,9 @@
 # Standardized arguments
 # ----------------------
 #
-# The `~proplot.wrappers.standardize_1d` wrapper is used to standardize
+# The `~proplot.axes.standardize_1d` wrapper is used to standardize
 # positional arguments across all 1D plotting methods.
-# `~proplot.wrappers.standardize_1d` allows you to optionally omit *x*
+# `~proplot.axes.standardize_1d` allows you to optionally omit *x*
 # coordinates, in which case they are inferred from the data. It also permits
 # passing 2D *y* coordinate arrays to any plotting method, in which case the
 # plotting method is called for each column of the array.
@@ -100,7 +100,7 @@
     # Plot by passing both x and y coordinates
     ax = axs[0]
     ax.area(x, -1 * y / N, stacked=True)
-    ax.bar(x, y, linewidth=0, alpha=1, width=0.8 * (x[1] - x[0]))
+    ax.bar(x, y, linewidth=0, alpha=1, width=0.8)
     ax.plot(x, y + 1, linewidth=2)
     ax.scatter(x, y + 2, marker='s', markersize=5**2)
     ax.format(title='Manual x coordinates')
@@ -122,7 +122,7 @@
 # Pandas and xarray integration
 # -----------------------------
 #
-# The `~proplot.wrappers.standardize_1d` wrapper integrates 1D plotting
+# The `~proplot.axes.standardize_1d` wrapper integrates 1D plotting
 # methods with pandas `~pandas.DataFrame`\ s and xarray `~xarray.DataArray`\ s.
 # When you pass a DataFrame or DataArray to any plotting command, the x-axis
 # label, y-axis label, legend label, colorbar label, and/or title are
@@ -185,20 +185,20 @@
 # Adding error bars
 # -----------------
 #
-# The `~proplot.wrappers.add_errorbars` wrapper lets you draw error bars
+# The `~proplot.axes.add_errorbars` wrapper lets you draw error bars
 # on-the-fly by passing certain keyword arguments to
 # `~matplotlib.axes.Axes.plot`, `~matplotlib.axes.Axes.scatter`,
 # `~matplotlib.axes.Axes.bar`, or `~matplotlib.axes.Axes.barh`.
 #
 # If you pass 2D arrays to these methods with ``means=True`` or
 # ``medians=True``, the means or medians of each column are drawn as points,
 # lines, or bars, and error bars are drawn to represent the spread in each
-# column. `~proplot.wrappers.add_errorbars` lets you draw both thin error
+# column. `~proplot.axes.add_errorbars` lets you draw both thin error
 # "bars" with optional whiskers, and thick error "boxes" overlayed on top of
 # these bars (this can be used to represent different percentil ranges).
 # Instead of using 2D arrays, you can also pass error bar coordinates
 # *manually* with the `bardata` and `boxdata` keyword arguments. See
-# `~proplot.wrappers.add_errorbars` for details.
+# `~proplot.axes.add_errorbars` for details.
 
 # %%
 import proplot as plot
@@ -254,8 +254,8 @@
 # ------------------------
 #
 # The `~matplotlib.axes.Axes.bar` and `~matplotlib.axes.Axes.barh` methods
-# are wrapped by `~proplot.wrappers.bar_wrapper`,
-# `~proplot.wrappers.cycle_changer`, and `~proplot.wrappers.standardize_1d`.
+# are wrapped by `~proplot.axes.bar_wrapper`,
+# `~proplot.axes.cycle_changer`, and `~proplot.axes.standardize_1d`.
 # You can now *group* or *stack* columns of data by passing 2D arrays to
 # `~matplotlib.axes.Axes.bar` or `~matplotlib.axes.Axes.barh`, just like in
 # `pandas`. Also, `~matplotlib.axes.Axes.bar` and `~matplotlib.axes.Axes.barh`
@@ -266,8 +266,8 @@
 # `~proplot.axes.Axes.areax` methods. These are alises for
 # `~matplotlib.axes.Axes.fill_between` and
 # `~matplotlib.axes.Axes.fill_betweenx`, which are now wrapped by
-# `~proplot.wrappers.fill_between_wrapper` and
-# `~proplot.wrappers.fill_betweenx_wrapper`. You can now *stack* or *overlay*
+# `~proplot.axes.fill_between_wrapper` and
+# `~proplot.axes.fill_betweenx_wrapper`. You can now *stack* or *overlay*
 # columns of data by passing 2D arrays to `~proplot.axes.Axes.area` and
 # `~proplot.axes.Axes.areax`, just like in `pandas`. You can also now draw
 # area plots that *change color* when the fill boundaries cross each other by
@@ -350,9 +350,9 @@
 # --------------------------
 #
 # The `~matplotlib.axes.Axes.boxplot` and `~matplotlib.axes.Axes.violinplot`
-# methods are now wrapped with `~proplot.wrappers.boxplot_wrapper`,
-# `~proplot.wrappers.violinplot_wrapper`, `~proplot.wrappers.cycle_changer`,
-# and `~proplot.wrappers.standardize_1d`. These wrappers add some useful
+# methods are now wrapped with `~proplot.axes.boxplot_wrapper`,
+# `~proplot.axes.violinplot_wrapper`, `~proplot.axes.cycle_changer`,
+# and `~proplot.axes.standardize_1d`. These wrappers add some useful
 # options and apply aesthetically pleasing default settings. They also
 # automatically apply axis labels based on the `~pandas.DataFrame` column
 # labels or the input *x* coordinate labels.
@@ -446,7 +446,7 @@
     xlim=(-1, 1), ylim=(-1, 1), title='Step gradations',
     xlabel='cosine angle', ylabel='sine angle'
 )
-ax.colorbar(m, loc='b', maxn=10, label=f'parametric coordinate')
+ax.colorbar(m, loc='b', maxn=10, label='parametric coordinate')
 
 
 # %% [raw] raw_mimetype="text/restructuredtext"
@@ -456,8 +456,8 @@
 # -------------
 #
 # The `~matplotlib.axes.Axes.scatter` method is now wrapped by
-# `~proplot.wrappers.scatter_wrapper`, `~proplot.wrappers.cycle_changer`, and
-# `~proplot.wrappers.standardize_1d`. This means that
+# `~proplot.axes.scatter_wrapper`, `~proplot.axes.cycle_changer`, and
+# `~proplot.axes.standardize_1d`. This means that
 # `~matplotlib.axes.Axes.scatter` now accepts 2D arrays, just like
 # `~matplotlib.axes.Axes.plot`. Also, successive calls to
 # `~matplotlib.axes.Axes.scatter` now use the property cycler properties

docs/2dplots.py

@@ -39,14 +39,14 @@
 #
 # It is often desirable to create ProPlot colormaps on-the-fly, without
 # explicitly using the `~proplot.constructor.Colormap` constructor function.
-# To enable this, the `~proplot.wrappers.cmap_changer` wrapper adds the
+# To enable this, the `~proplot.axes.cmap_changer` wrapper adds the
 # `cmap` and `cmap_kw` arguments to every 2D plotting method. These
 # arguments are passed to the `~proplot.constructor.Colormap` constructor
 # function, and the resulting colormap is used for the input data. For
 # example, to create and apply a monochromatic colormap, you can simply use
 # ``cmap='color name'``.
 
-# The `~proplot.wrappers.cmap_changer` wrapper also
+# The `~proplot.axes.cmap_changer` wrapper also
 # adds the `norm` and `norm_kw` arguments. They are passed to the
 # `~proplot.constructor.Norm` constructor function, and the resulting
 # normalizer is used for the input data. For more information on colormaps
@@ -80,7 +80,7 @@
 # Discrete colormap levels
 # ------------------------
 #
-# The `~proplot.wrappers.cmap_changer` wrapper also applies the
+# The `~proplot.axes.cmap_changer` wrapper also applies the
 # `~proplot.colors.DiscreteNorm` normalizer to every colormap plot.
 # `~proplot.colors.DiscreteNorm` converts data values to colormap colors by (1)
 # transforming data using an arbitrary *continuous* normalizer (e.g.
@@ -212,7 +212,7 @@
 # Standardized arguments
 # ----------------------
 #
-# The `~proplot.wrappers.standardize_2d` wrapper is used to standardize
+# The `~proplot.axes.standardize_2d` wrapper is used to standardize
 # positional arguments across all 2D plotting methods.  Among other things,
 # it guesses coordinate *edges* for `~matplotlib.axes.Axes.pcolor` and
 # `~matplotlib.axes.Axes.pcolormesh` plots when you supply coordinate
@@ -255,7 +255,7 @@
 # Pandas and xarray integration
 # -----------------------------
 #
-# The `~proplot.wrappers.standardize_2d` wrapper also integrates 2D
+# The `~proplot.axes.standardize_2d` wrapper also integrates 2D
 # plotting methods with pandas `~pandas.DataFrame`\ s and xarray
 # `~xarray.DataArray`\ s. When you pass a DataFrame or DataArray to any
 # plotting command, the x-axis label, y-axis label, legend label, colorbar
@@ -272,19 +272,20 @@
 
 # DataArray
 state = np.random.RandomState(51423)
-data = 50 * (
-    np.sin(np.linspace(0, 2 * np.pi, 20) + 0) ** 2
-    * np.cos(np.linspace(0, np.pi, 20) + np.pi / 2)[:, None] ** 2
+linspace = np.linspace(0, np.pi, 20)
+data = 50 * state.normal(1, 0.2, size=(20, 20)) * (
+    np.sin(linspace * 2) ** 2
+    * np.cos(linspace + np.pi / 2)[:, None] ** 2
 )
 lat = xr.DataArray(
     np.linspace(-90, 90, 20),
     dims=('lat',),
-    attrs={'units': 'degN'}
+    attrs={'units': 'deg_north'}
 )
 plev = xr.DataArray(
     np.linspace(1000, 0, 20),
     dims=('plev',),
-    attrs={'long_name': 'pressure', 'units': 'hPa'}
+    attrs={'long_name': 'pressure', 'units': 'mb'}
 )
 da = xr.DataArray(
     data,
@@ -295,14 +296,14 @@
 )
 
 # DataFrame
-data = state.rand(20, 20)
+data = state.rand(12, 20)
 df = pd.DataFrame(
-    data.cumsum(axis=0).cumsum(axis=1),
-    index=[*'JFMAMJJASONDJFMAMJJA']
+    (data - 0.4).cumsum(axis=0).cumsum(axis=1),
+    index=list('JFMAMJJASOND'),
 )
 df.name = 'temporal data'
-df.index.name = 'index'
-df.columns.name = 'time (days)'
+df.index.name = 'month'
+df.columns.name = 'variable (units)'
 
 # %%
 import proplot as plot
@@ -311,13 +312,13 @@
 
 # Plot DataArray
 axs[0].contourf(
-    da, cmap='RdPu', cmap_kw={'left': 0.05}, colorbar='l', lw=0.7, color='gray7'
+    da, cmap='RdPu', cmap_kw={'left': 0.05}, colorbar='l', lw=0.7, color='k'
 )
 axs[0].format(yreverse=True)
 
 # Plot DataFrame
 axs[1].contourf(
-    df, cmap='YlOrRd', colorbar='r', linewidth=0.7, color='gray7'
+    df, cmap='YlOrRd', colorbar='r', linewidth=0.7, color='k'
 )
 axs[1].format(xtickminor=False)
 
@@ -328,19 +329,19 @@
 # Contour and gridbox labels
 # --------------------------
 #
-# The `~proplot.wrappers.cmap_changer` wrapper also allows you to quickly add
+# The `~proplot.axes.cmap_changer` wrapper also allows you to quickly add
 # *labels* to `~proplot.axes.Axes.heatmap`, `~matplotlib.axes.Axes.pcolor`,
 # `~matplotlib.axes.Axes.pcolormesh`, `~matplotlib.axes.Axes.contour`, and
 # `~matplotlib.axes.Axes.contourf` plots by simply using ``labels=True``.
 # Critically, the label text is colored black or white depending on the
 # luminance of the underlying grid box or filled contour.
 #
-# `~proplot.wrappers.cmap_changer` draws contour labels with
+# `~proplot.axes.cmap_changer` draws contour labels with
 # `~matplotlib.axes.Axes.clabel` and grid box labels with
 # `~matplotlib.axes.Axes.text`. You can pass keyword arguments to these
 # functions using the `labels_kw` dictionary keyword argument, and change the
 # label precision with the `precision` keyword argument. See
-# `~proplot.wrappers.cmap_changer` for details.
+# `~proplot.axes.cmap_changer` for details.
 
 # %%
 import proplot as plot

docs/api.rst

@@ -28,7 +28,7 @@ Axes classes
 
 .. automodsumm:: proplot.axes
    :toctree: api
-   :skip: ProjAxes, XYAxes
+   :classes-only:
 
 
 Constructor functions
@@ -52,13 +52,15 @@ Configuration tools
 Plotting wrappers
 =================
 
-.. automodule:: proplot.wrappers
+.. automodule:: proplot.axes.plot
 
-.. automodsumm:: proplot.wrappers
+.. automodsumm:: proplot.axes
    :toctree: api
+   :functions-only:
+   :skip: ProjAxes, XYAxes
 
 
-Show functions
+Demo functions
 ==============
 
 .. automodule:: proplot.demos

docs/axis.py

@@ -269,8 +269,8 @@
 # %% [raw] raw_mimetype="text/restructuredtext"
 # .. _ug_scales:
 #
-# Axis scales
-# -----------
+# Changing the axis scale
+# -----------------------
 #
 # "Axis scales" like ``'linear'`` and ``'log'`` control the *x* and *y* axis
 # coordinate system. To change the axis scale, simply pass e.g.
@@ -448,8 +448,7 @@
 # In the latter case, the scale's transforms are used for the forward and
 # inverse functions, and the scale's default locators and formatters are used
 # for the default `~proplot.scale.FuncScale` locators and formatters.
-#
-# Notably, the "parent" axis scale is now *arbitrary* -- in the first example
+# Note that the "parent" axis scale is now arbitrary -- in the first example
 # shown below, we create a `~proplot.axes.CartesianAxes.dualx` axis for an
 # axis scaled by the ``'symlog'`` scale.
 

docs/colorbars_legends.py

@@ -43,8 +43,8 @@
 # `~matplotlib.axes.Axes.contourf`). To draw a legend or colorbar-legend in
 # one go, pass a location (e.g. ``legend='r'`` or ``colorbar='r'``) to
 # methods that accept a `cycle` argument (e.g. `~matplotlib.axes.Axes.plot`).
-# This feature is powered by the `~proplot.wrappers.cmap_changer` and
-# `~proplot.wrappers.cycle_changer` wrappers.
+# This feature is powered by the `~proplot.axes.cmap_changer` and
+# `~proplot.axes.cycle_changer` wrappers.
 #
 # Finally, just like matplotlib "inset" legends, ProPlot also supports
 # "inset" *colorbars*. To draw an inset colorbar, pass an inset location to
@@ -185,7 +185,7 @@
 #
 # The `~proplot.figure.Figure` `~proplot.figure.Figure.colorbar` and
 # `~proplot.axes.Axes` `~proplot.axes.Axes.colorbar` methods are wrapped by
-# `~proplot.wrappers.colorbar_wrapper`, which adds several new features.
+# `~proplot.axes.colorbar_wrapper`, which adds several new features.
 #
 # You can now draw colorbars from *lists of colors* or *lists of artists* by
 # passing a list instead of a mappable object. Colorbar minor ticks are now
@@ -243,7 +243,7 @@
 #
 # The `~proplot.figure.Figure` `~proplot.figure.Figure.legend` and
 # `~proplot.axes.Axes` `~proplot.axes.Axes.legend` methods are wrapped by
-# `~proplot.wrappers.legend_wrapper`, which adds several new features.
+# `~proplot.axes.legend_wrapper`, which adds several new features.
 #
 # You can draw legends with *centered legend rows*, either by passing
 # ``center=True`` or by passing *list of lists* of plot handles. This is

docs/colormaps.py

@@ -139,7 +139,7 @@
 # your convenience, most of these features can be accessed via the
 # `~proplot.constructor.Colormap` constructor function. Note that every
 # plotting command that accepts a `cmap` keyword passes it through this
-# function (see `~proplot.wrappers.cmap_changer`).
+# function (see `~proplot.axes.cmap_changer`).
 #
 # To make `~proplot.colors.PerceptuallyUniformColormap`\ s from scratch, you
 # have the following three options:

docs/conf.py

@@ -74,7 +74,7 @@
     'sphinx_copybutton',
     'sphinx_automodapi.automodapi',  # see: https://github.com/lukelbd/sphinx-automodapi/tree/proplot-mods # noqa
     'nbsphinx',
-    ]
+]
 
 extlinks = {
     'issue': ('https://github.com/lukelbd/proplot/issues/%s', 'GH#'),