From 6447c953f303d9a6abba68f7b5af09f14f22f073 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Sun, 25 Apr 2021 00:12:07 +0200 Subject: [PATCH] Very soft-deprecate AxesDivider.new_{horizontal,vertical}. `append_axes` is a more general API which is basically just as ergonomic, and avoids exposing the slightly unusual feature of axes_grid having indices increasing towards the top for vertical stacks (contrary to gridspec which goes towards the bottom), and hence `new_vertical(append_start={True,False})` behaving in the opposite direction as one may naively expect. Given that `new_horizontal` and `new_vertical` would basically stay as helpers, it seems overkill to deprecate them, but perhaps we can at least hide them from the docs (`:meta private:`). Also promote `axes_class` to be a plain normal parameter. --- .../api_changes_3.5.0/behaviour.rst | 4 +- examples/axes_grid1/demo_axes_divider.py | 4 +- .../make_room_for_ylabel_using_axesgrid.py | 2 +- lib/mpl_toolkits/axes_grid1/axes_divider.py | 88 ++++++++----------- 4 files changed, 42 insertions(+), 56 deletions(-) diff --git a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst index 62cdb0a32854..fb5211aa2209 100644 --- a/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst +++ b/doc/api/prev_api_changes/api_changes_3.5.0/behaviour.rst @@ -242,6 +242,6 @@ location of values that lie between two levels. ``AxesDivider`` now defaults to rcParams-specified pads ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -`.AxesDivider.append_axes`, `.AxesDivider.new_horizontal`, and -`.AxesDivider.new_vertical` now default to paddings specified by +`.AxesDivider.append_axes`, ``AxesDivider.new_horizontal``, and +``AxesDivider.new_vertical`` now default to paddings specified by :rc:`figure.subplot.wspace` and :rc:`figure.subplot.hspace` rather than zero. diff --git a/examples/axes_grid1/demo_axes_divider.py b/examples/axes_grid1/demo_axes_divider.py index 51f1e4c25491..c800c263a453 100644 --- a/examples/axes_grid1/demo_axes_divider.py +++ b/examples/axes_grid1/demo_axes_divider.py @@ -68,7 +68,7 @@ def demo_locatable_axes_easy(ax): divider = make_axes_locatable(ax) - ax_cb = divider.new_horizontal(size="5%", pad=0.05) + ax_cb = divider.append_axes("right", size="5%", pad=0.05) fig = ax.get_figure() fig.add_axes(ax_cb) @@ -86,7 +86,7 @@ def demo_images_side_by_side(ax): divider = make_axes_locatable(ax) Z, extent = get_demo_image() - ax2 = divider.new_horizontal(size="100%", pad=0.05) + ax2 = divider.append_axes("right", size="100%", pad=0.05) fig1 = ax.get_figure() fig1.add_axes(ax2) diff --git a/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py b/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py index b6ce60531741..7049962b035d 100644 --- a/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py +++ b/examples/axes_grid1/make_room_for_ylabel_using_axesgrid.py @@ -40,7 +40,7 @@ ax1 = plt.axes([0, 0, 1, 1]) divider = make_axes_locatable(ax1) -ax2 = divider.new_horizontal("100%", pad=0.3, sharey=ax1) +ax2 = divider.append_axes("right", "100%", pad=0.3, sharey=ax1) ax2.tick_params(labelleft=False) fig.add_axes(ax2) diff --git a/lib/mpl_toolkits/axes_grid1/axes_divider.py b/lib/mpl_toolkits/axes_grid1/axes_divider.py index 43e23b1c3101..9a36285fd856 100644 --- a/lib/mpl_toolkits/axes_grid1/axes_divider.py +++ b/lib/mpl_toolkits/axes_grid1/axes_divider.py @@ -442,26 +442,11 @@ def _get_new_axes(self, *, axes_class=None, **kwargs): def new_horizontal(self, size, pad=None, pack_start=False, **kwargs): """ - Add a new axes on the right (or left) side of the main axes. + Helper method for ``append_axes("left")`` and ``append_axes("right")``. - Parameters - ---------- - size : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str - The axes width. float or str arguments are interpreted as - ``axes_size.from_any(size, AxesX())``. - pad : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str - Padding between the axes. float or str arguments are interpreted - as ``axes_size.from_any(size, AxesX())``. Defaults to - :rc:`figure.subplot.wspace` times the main axes width. - pack_start : bool - If False, the new axes is appended at the end - of the list, i.e., it became the right-most axes. If True, it is - inserted at the start of the list, and becomes the left-most axes. - **kwargs - All extra keywords arguments are passed to the created axes. - If *axes_class* is given, the new axes will be created as an - instance of the given class. Otherwise, the same class of the - main axes will be used. + See the documentation of `append_axes` for more details. + + :meta private: """ if pad is None: pad = mpl.rcParams["figure.subplot.wspace"] * self._xref @@ -489,26 +474,11 @@ def new_horizontal(self, size, pad=None, pack_start=False, **kwargs): def new_vertical(self, size, pad=None, pack_start=False, **kwargs): """ - Add a new axes on the top (or bottom) side of the main axes. + Helper method for ``append_axes("top")`` and ``append_axes("bottom")``. - Parameters - ---------- - size : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str - The axes height. float or str arguments are interpreted as - ``axes_size.from_any(size, AxesY())``. - pad : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str - Padding between the axes. float or str arguments are interpreted - as ``axes_size.from_any(size, AxesY())``. Defaults to - :rc:`figure.subplot.hspace` times the main axes height. - pack_start : bool - If False, the new axes is appended at the end - of the list, i.e., it became the right-most axes. If True, it is - inserted at the start of the list, and becomes the left-most axes. - **kwargs - All extra keywords arguments are passed to the created axes. - If *axes_class* is given, the new axes will be created as an - instance of the given class. Otherwise, the same class of the - main axes will be used. + See the documentation of `append_axes` for more details. + + :meta private: """ if pad is None: pad = mpl.rcParams["figure.subplot.hspace"] * self._yref @@ -529,31 +499,47 @@ def new_vertical(self, size, pad=None, pack_start=False, **kwargs): else: self._vertical.append(size) locator = self.new_locator( - nx=self._xrefindex, ny=len(self._vertical)-1) + nx=self._xrefindex, ny=len(self._vertical) - 1) ax = self._get_new_axes(**kwargs) ax.set_axes_locator(locator) return ax @_api.delete_parameter("3.5", "add_to_figure", alternative="ax.remove()") - def append_axes(self, position, size, pad=None, add_to_figure=True, - **kwargs): + def append_axes(self, position, size, pad=None, add_to_figure=True, *, + axes_class=None, **kwargs): """ - Create an axes at the given *position* with the same height - (or width) of the main axes. - - *position* - ["left"|"right"|"bottom"|"top"] + Add a new axes on a given side of the main axes. - *size* and *pad* should be axes_grid.axes_size compatible. + Parameters + ---------- + position : {"left", "right", "bottom", "top"} + Where the new axes is positioned relative to the main axes. + size : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str + The axes width or height. float or str arguments are interpreted + as ``axes_size.from_any(size, AxesX())`` for left or + right axes, and likewise with ``AxesY`` for bottom or top axes. + pad : :mod:`~mpl_toolkits.axes_grid1.axes_size` or float or str + Padding between the axes. float or str arguments are interpreted + as for *size*. Defaults to :rc:`figure.subplot.wspace` times the + main axes width (left or right axes) or :rc:`figure.subplot.hspace` + times the main axes height (bottom or top axes). + axes_class : subclass type of `~.axes.Axes`, optional + The type of the new axes. Defaults to the type of the main axes. + **kwargs + All extra keywords arguments are passed to the created axes. """ if position == "left": - ax = self.new_horizontal(size, pad, pack_start=True, **kwargs) + ax = self.new_horizontal( + size, pad, pack_start=True, axes_class=axes_class, **kwargs) elif position == "right": - ax = self.new_horizontal(size, pad, pack_start=False, **kwargs) + ax = self.new_horizontal( + size, pad, pack_start=False, axes_class=axes_class, **kwargs) elif position == "bottom": - ax = self.new_vertical(size, pad, pack_start=True, **kwargs) + ax = self.new_vertical( + size, pad, pack_start=True, axes_class=axes_class, **kwargs) elif position == "top": - ax = self.new_vertical(size, pad, pack_start=False, **kwargs) + ax = self.new_vertical( + size, pad, pack_start=False, axes_class=axes_class, **kwargs) else: _api.check_in_list(["left", "right", "bottom", "top"], position=position)