ENH/FIX: Don't auto reposition axes if axes.titlepad not None

jklymak · jklymak · commit b35cc73fdbb5 · 2020-04-04T14:15:09.000-07:00
Automatic title repositioning is now suppressed if the title padding
is set to a non-None value by the user (either in the pad kwarg, or
the rcParam axes.titlepad)
diff --git a/doc/api/next_api_changes/behaviour.rst b/doc/api/next_api_changes/behaviour.rst
@@ -98,9 +98,9 @@ deprecation warning.
 `~.Axes.errorbar` now color cycles when only errorbar color is set
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Previously setting the *ecolor* would turn off automatic color cycling for the plot, leading to the 
-the lines and markers defaulting to whatever the first color in the color cycle was in the case of 
-multiple plot calls. 
+Previously setting the *ecolor* would turn off automatic color cycling for the plot, leading to
+the lines and markers defaulting to whatever the first color in the color cycle was in the case of
+multiple plot calls.
 
 `.rcsetup.validate_color_for_prop_cycle` now always raises TypeError for bytes input
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -155,3 +155,15 @@ support for it will be dropped in a future Matplotlib release.
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Previously, keyword arguments were silently ignored when no positional
 arguments were given.
+
+:rc:`axes.titlepad` and *pad* argument of `~.Axes.set_title` now default to ``None``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Since 3.0, Axes titles are automatically repositioned, primarily to avoid
+xlabels or xticks at the top of the axes.  The user could turn this
+off using the optional *y* argument to `~.Axes.set_title`).  However, that
+made it impossible to manually set the *pad* argument (without also setting the
+*y* argument).  Now *pad* defaults to ``None`` and the
+rcParam :rc:`axes.titlepad` defaults to ``None``, which will
+allow automatic title placement.  However, if these are set to a float, then
+the automatic placement of the title is turned off.
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -169,8 +169,14 @@ def set_title(self, label, fontdict=None, loc=None, pad=None, **kwargs):
         titlecolor = rcParams['axes.titlecolor']
         if not cbook._str_lower_equal(titlecolor, 'auto'):
             default["color"] = titlecolor
+
         if pad is None:
             pad = rcParams['axes.titlepad']
+        if pad is not None:
+            self._autotitlepos = False
+        else:
+            pad = 6  # default.
+
         self._set_title_offset_trans(float(pad))
         title.set_text(label)
         title.update(default)
diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py
@@ -1061,11 +1061,9 @@ def cla(self):
             verticalalignment='baseline',
             horizontalalignment='right',
             )
-        title_offset_points = mpl.rcParams['axes.titlepad']
-        # refactor this out so it can be called in ax.set_title if
-        # pad argument used...
-        self._set_title_offset_trans(title_offset_points)
-        # determine if the title position has been set manually:
+        # this needs to be called in case cla is not called on
+        # axes later...
+        self._set_title_offset_trans(mpl.rcParams['axes.titlepad'])
         self._autotitlepos = None
 
         for _title in (self.title, self._left_title, self._right_title):
@@ -1123,6 +1121,9 @@ def _set_title_offset_trans(self, title_offset_points):
         Set the offset for the title either from :rc:`axes.titlepad`
         or from set_title kwarg ``pad``.
         """
+        if title_offset_points is None:
+            # dummy default in case cla hasn't been called.
+            title_offset_points = 0
         self.titleOffsetTrans = mtransforms.ScaledTranslation(
                 0.0, title_offset_points / 72,
                 self.figure.dpi_scale_trans)
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
@@ -1219,7 +1219,7 @@ def _convert_validator_spec(key, conv):
     'axes.titlelocation':    ['center', ['left', 'center', 'right']],  # alignment of axes title
     'axes.titleweight':      ['normal', validate_fontweight],  # font weight of axes title
     'axes.titlecolor':       ['auto', validate_color_or_auto],  # font color of axes title
-    'axes.titlepad':         [6.0, validate_float],  # pad from axes top to title in points
+    'axes.titlepad':         [None, validate_float_or_None],  # pad from axes top to title in points; None means allow auto position of title
     'axes.grid':             [False, validate_bool],   # display grid or not
     'axes.grid.which':       ['major', ['minor', 'both', 'major']],  # set whether the grid is drawn on
                                                                      # 'major' 'minor' or 'both' ticks
diff --git a/lib/matplotlib/tests/test_axes.py b/lib/matplotlib/tests/test_axes.py
@@ -5523,6 +5523,8 @@ def test_titlesetpos():
 def test_title_xticks_top():
     # Test that title moves if xticks on top of axes.
     fig, ax = plt.subplots()
+    # set to the new default (from 5, which will suppress title reposition)
+    mpl.rcParams['axes.titlepad'] = None
     ax.xaxis.set_ticks_position('top')
     ax.set_title('xlabel top')
     fig.canvas.draw()
@@ -5532,13 +5534,26 @@ def test_title_xticks_top():
 def test_title_xticks_top_both():
     # Test that title moves if xticks on top of axes.
     fig, ax = plt.subplots()
+    # set to the new default (from 5, which will suppress title reposition)
+    mpl.rcParams['axes.titlepad'] = None
     ax.tick_params(axis="x",
                    bottom=True, top=True, labelbottom=True, labeltop=True)
     ax.set_title('xlabel top')
     fig.canvas.draw()
     assert ax.title.get_position()[1] > 1.04
 
 
+def test_title_noauto_pad():
+    # test that if we pad, then the title does not autopos
+
+    fig, ax = plt.subplots()
+    ax.set_title("Title 1", pad=-20)
+    ax.tick_params(axis="x",
+                   bottom=True, top=True, labelbottom=True, labeltop=True)
+    fig.canvas.draw()
+    assert ax.title.get_position()[1] == 1.0
+
+
 def test_offset_label_color():
     # Tests issue 6440
     fig = plt.figure()
diff --git a/lib/matplotlib/tests/test_tightlayout.py b/lib/matplotlib/tests/test_tightlayout.py
@@ -19,7 +19,7 @@ def example_plot(ax, fontsize=12):
     ax.set_title('Title', fontsize=fontsize)
 
 
-@image_comparison(['tight_layout1'])
+@image_comparison(['tight_layout1'], tol=1.87)
 def test_tight_layout1():
     """Test tight_layout for a single subplot."""
     fig, ax = plt.subplots()
@@ -115,7 +115,7 @@ def test_tight_layout6():
                          h_pad=0.45)
 
 
-@image_comparison(['tight_layout7'])
+@image_comparison(['tight_layout7'], tol=1.87)
 def test_tight_layout7():
     # tight layout with left and right titles
     fontsize = 24
diff --git a/matplotlibrc.template b/matplotlibrc.template
@@ -326,7 +326,7 @@
 #mathtext.sf:  sans
 #mathtext.tt:  monospace
 #mathtext.fallback: cm  # Select fallback font from ['cm' (Computer Modern), 'stix'
-                        # 'stixsans'] when a symbol can not be found in one of the 
+                        # 'stixsans'] when a symbol can not be found in one of the
                         # custom math fonts. Select 'None' to not perform fallback
                         # and replace the missing character by a dummy symbol.
 #mathtext.default: it  # The default font to use for math.
@@ -352,7 +352,7 @@
 #axes.titleweight:   normal  # font weight of title
 #axes.titlecolor:    auto    # color of the axes title, auto falls back to
                              # text.color as default value
-#axes.titlepad:      6.0     # pad between axes and title in points
+#axes.titlepad:      None     # pad between axes and title in points, None means allow automatic positioning
 #axes.labelsize:     medium  # fontsize of the x any y labels
 #axes.labelpad:      4.0     # space between label and axis
 #axes.labelweight:   normal  # weight of the x and y labels
