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

jklymak · jklymak · commit c88e7c8f17e3 · 2020-04-13T14:43:02.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/api_changes_3.3/behaviour.rst b/doc/api/api_changes_3.3/behaviour.rst
@@ -98,7 +98,7 @@ 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
+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.
 
@@ -171,3 +171,15 @@ The default method used to format `.Slider` values has been changed to use a
 values are displayed with an appropriate number of significant digits even if
 they are much smaller or much bigger than 1.  To restore the old behavior,
 explicitly pass a "%1.2f" as the *valfmt* parameter to `.Slider`.
+
+: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
@@ -1139,11 +1139,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):
@@ -1200,6 +1198,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
