1- from collections .abc import MutableSequence
1+ from collections .abc import Iterable , MutableSequence
22from contextlib import ExitStack
33import functools
44import inspect
1818import matplotlib .collections as mcoll
1919import matplotlib .colors as mcolors
2020import matplotlib .font_manager as font_manager
21+ from matplotlib .gridspec import SubplotSpec
2122import matplotlib .image as mimage
2223import matplotlib .lines as mlines
2324import matplotlib .patches as mpatches
@@ -569,8 +570,8 @@ def __str__(self):
569570return "{0}({1[0]:g},{1[1]:g};{1[2]:g}x{1[3]:g})" .format (
570571type (self ).__name__ ,self ._position .bounds )
571572
572- def __init__ (self ,fig ,rect ,
573- * ,
573+ def __init__ (self ,fig ,
574+ * args ,
574575facecolor = None ,# defaults to rc axes.facecolor
575576frameon = True ,
576577sharex = None ,# use Axes instance's xaxis info
@@ -589,9 +590,18 @@ def __init__(self, fig, rect,
589590 fig : `~matplotlib.figure.Figure`
590591 The Axes is built in the `.Figure` *fig*.
591592
592- rect : tuple (left, bottom, width, height).
593- The Axes is built in the rectangle *rect*. *rect* is in
594- `.Figure` coordinates.
593+ *args
594+ ``*args`` can be a single ``(left, bottom, width, height)``
595+ rectangle or a single `.Bbox`. This specifies the rectangle (in
596+ figure coordinates) where the Axes is positioned.
597+
598+ ``*args`` can also consist of three numbers or a single three-digit
599+ number; in the latter case, the digits are considered as
600+ independent numbers. The numbers are interpreted as ``(nrows,
601+ ncols, index)``: ``(nrows, ncols)`` specifies the size of an array
602+ of subplots, and ``index`` is the 1-based index of the subplot
603+ being created. Finally, ``*args`` can also directly be a
604+ `.SubplotSpec` instance.
595605
596606 sharex, sharey : `~.axes.Axes`, optional
597607 The x or y `~.matplotlib.axis` is shared with the x or
@@ -616,10 +626,21 @@ def __init__(self, fig, rect,
616626 """
617627
618628super ().__init__ ()
619- if isinstance (rect ,mtransforms .Bbox ):
620- self ._position = rect
629+ if "rect" in kwargs :
630+ if args :
631+ raise TypeError (
632+ "'rect' cannot be used together with positional arguments" )
633+ rect = kwargs .pop ("rect" )
634+ _api .check_isinstance ((mtransforms .Bbox ,Iterable ),rect = rect )
635+ args = (rect ,)
636+ self ._subplotspec = subplotspec = None
637+ if len (args )== 1 and isinstance (args [0 ],mtransforms .Bbox ):
638+ self ._position = args [0 ]
639+ elif len (args )== 1 and np .iterable (args [0 ]):
640+ self ._position = mtransforms .Bbox .from_bounds (* args [0 ])
621641else :
622- self ._position = mtransforms .Bbox .from_bounds (* rect )
642+ self ._position = self ._originalPosition = mtransforms .Bbox .unit ()
643+ subplotspec = SubplotSpec ._from_subplot_args (fig ,args )
623644if self ._position .width < 0 or self ._position .height < 0 :
624645raise ValueError ('Width and height specified must be non-negative' )
625646self ._originalPosition = self ._position .frozen ()
@@ -632,8 +653,14 @@ def __init__(self, fig, rect,
632653self ._sharey = sharey
633654self .set_label (label )
634655self .set_figure (fig )
656+ # The subplotspec needs to be set after the figure (so that
657+ # figure-level subplotpars are taken into account), but the figure
658+ # needs to be set after self._position is initialized.
659+ if subplotspec :
660+ self .set_subplotspec (subplotspec )
635661self .set_box_aspect (box_aspect )
636662self ._axes_locator = None # Optionally set via update(kwargs).
663+
637664# placeholder for any colorbars added that use this Axes.
638665# (see colorbar.py):
639666self ._colorbars = []
@@ -737,6 +764,19 @@ def __repr__(self):
737764fields += [f"{ name } { axis .get_label ().get_text ()!r} ]
738765return f"<{ self .__class__ .__name__ } + ", " .join (fields )+ ">"
739766
767+ def get_subplotspec (self ):
768+ """Return the `.SubplotSpec` associated with the subplot, or None."""
769+ return self ._subplotspec
770+
771+ def set_subplotspec (self ,subplotspec ):
772+ """Set the `.SubplotSpec`. associated with the subplot."""
773+ self ._subplotspec = subplotspec
774+ self ._set_position (subplotspec .get_position (self .figure ))
775+
776+ def get_gridspec (self ):
777+ """Return the `.GridSpec` associated with the subplot, or None."""
778+ return self ._subplotspec .get_gridspec ()
779+
740780@_api .delete_parameter ("3.6" ,"args" )
741781@_api .delete_parameter ("3.6" ,"kwargs" )
742782def get_window_extent (self ,renderer = None ,* args ,** kwargs ):
@@ -4439,15 +4479,22 @@ def _make_twin_axes(self, *args, **kwargs):
44394479"""Make a twinx Axes of self. This is used for twinx and twiny."""
44404480# Typically, SubplotBase._make_twin_axes is called instead of this.
44414481if 'sharex' in kwargs and 'sharey' in kwargs :
4442- raise ValueError ("Twinned Axes may share only one axis" )
4443- ax2 = self .figure .add_axes (
4444- self .get_position (True ),* args ,** kwargs ,
4445- axes_locator = _TransformedBoundsLocator (
4446- [0 ,0 ,1 ,1 ],self .transAxes ))
4482+ # The following line is added in v2.2 to avoid breaking Seaborn,
4483+ # which currently uses this internal API.
4484+ if kwargs ["sharex" ]is not self and kwargs ["sharey" ]is not self :
4485+ raise ValueError ("Twinned Axes may share only one axis" )
4486+ ss = self .get_subplotspec ()
4487+ if ss :
4488+ twin = self .figure .add_subplot (ss ,* args ,** kwargs )
4489+ else :
4490+ twin = self .figure .add_axes (
4491+ self .get_position (True ),* args ,** kwargs ,
4492+ axes_locator = _TransformedBoundsLocator (
4493+ [0 ,0 ,1 ,1 ],self .transAxes ))
44474494self .set_adjustable ('datalim' )
4448- ax2 .set_adjustable ('datalim' )
4449- self ._twinned_axes .join (self ,ax2 )
4450- return ax2
4495+ twin .set_adjustable ('datalim' )
4496+ self ._twinned_axes .join (self ,twin )
4497+ return twin
44514498
44524499def twinx (self ):
44534500"""
@@ -4515,3 +4562,56 @@ def get_shared_x_axes(self):
45154562def get_shared_y_axes (self ):
45164563"""Return an immutable view on the shared y-axes Grouper."""
45174564return cbook .GrouperView (self ._shared_axes ["y" ])
4565+
4566+ def label_outer (self ):
4567+ """
4568+ Only show "outer" labels and tick labels.
4569+
4570+ x-labels are only kept for subplots on the last row (or first row, if
4571+ labels are on the top side); y-labels only for subplots on the first
4572+ column (or last column, if labels are on the right side).
4573+ """
4574+ self ._label_outer_xaxis (check_patch = False )
4575+ self ._label_outer_yaxis (check_patch = False )
4576+
4577+ def _label_outer_xaxis (self ,* ,check_patch ):
4578+ # see documentation in label_outer.
4579+ if check_patch and not isinstance (self .patch ,mpl .patches .Rectangle ):
4580+ return
4581+ ss = self .get_subplotspec ()
4582+ if not ss :
4583+ return
4584+ label_position = self .xaxis .get_label_position ()
4585+ if not ss .is_first_row ():# Remove top label/ticklabels/offsettext.
4586+ if label_position == "top" :
4587+ self .set_xlabel ("" )
4588+ self .xaxis .set_tick_params (which = "both" ,labeltop = False )
4589+ if self .xaxis .offsetText .get_position ()[1 ]== 1 :
4590+ self .xaxis .offsetText .set_visible (False )
4591+ if not ss .is_last_row ():# Remove bottom label/ticklabels/offsettext.
4592+ if label_position == "bottom" :
4593+ self .set_xlabel ("" )
4594+ self .xaxis .set_tick_params (which = "both" ,labelbottom = False )
4595+ if self .xaxis .offsetText .get_position ()[1 ]== 0 :
4596+ self .xaxis .offsetText .set_visible (False )
4597+
4598+ def _label_outer_yaxis (self ,* ,check_patch ):
4599+ # see documentation in label_outer.
4600+ if check_patch and not isinstance (self .patch ,mpl .patches .Rectangle ):
4601+ return
4602+ ss = self .get_subplotspec ()
4603+ if not ss :
4604+ return
4605+ label_position = self .yaxis .get_label_position ()
4606+ if not ss .is_first_col ():# Remove left label/ticklabels/offsettext.
4607+ if label_position == "left" :
4608+ self .set_ylabel ("" )
4609+ self .yaxis .set_tick_params (which = "both" ,labelleft = False )
4610+ if self .yaxis .offsetText .get_position ()[0 ]== 0 :
4611+ self .yaxis .offsetText .set_visible (False )
4612+ if not ss .is_last_col ():# Remove right label/ticklabels/offsettext.
4613+ if label_position == "right" :
4614+ self .set_ylabel ("" )
4615+ self .yaxis .set_tick_params (which = "both" ,labelright = False )
4616+ if self .yaxis .offsetText .get_position ()[0 ]== 1 :
4617+ self .yaxis .offsetText .set_visible (False )