From e6893cf4083677cd580234992f6c291a24285e5f Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Wed, 13 Mar 2019 02:05:14 +0100 Subject: [PATCH] Clarify behavior of the 'tight' kwarg to autoscale/autoscale_view. The 'tight' kwarg behaves subtly differently in autoscale and in autoscale_view (in the former, it additionally sets the margins to zero). In autoscale_view, the default of tight=True actually has no effect in the default style, which disables it via an rcParam (which, by the way, is documented with a typo in matplotlibrc.template). Try to clarify these less-than-obvious behaviors. --- lib/matplotlib/axes/_base.py | 56 ++++++++++++++++++++++-------------- matplotlibrc.template | 2 +- 2 files changed, 35 insertions(+), 23 deletions(-) diff --git a/lib/matplotlib/axes/_base.py b/lib/matplotlib/axes/_base.py index f994a9812d71..cb1a1fbe10c8 100644 --- a/lib/matplotlib/axes/_base.py +++ b/lib/matplotlib/axes/_base.py @@ -1617,13 +1617,15 @@ def axis(self, *args, **kwargs): 'equal' Set equal scaling (i.e., make circles circular) by changing axis limits. 'scaled' Set equal scaling (i.e., make circles circular) by - changing dimensions of the plot box. - 'tight' Set limits just large enough to show all data. + changing dimensions of the plot box, then disable further + autoscaling. + 'tight' Set limits just large enough to show all data, then + disable further autoscaling. 'auto' Automatic scaling (fill plot box with data). 'normal' Same as 'auto'; deprecated. 'image' 'scaled' with axis limits equal to data limits. 'square' Square plot; similar to 'scaled', but initially forcing - ``xmax-xmin = ymax-ymin``. + ``xmax-xmin == ymax-ymin``. ======== ========================================================== emit : bool, optional, default *True* @@ -2348,16 +2350,12 @@ def autoscale(self, enable=True, axis='both', tight=None): None leaves the autoscaling state unchanged. axis : {'both', 'x', 'y'}, optional - which axis to operate on; default is 'both' + Which axis to operate on; default is 'both'. tight : bool or None, optional - If True, set view limits to data limits; - if False, let the locator and margins expand the view limits; - if None, use tight scaling if the only artist is an image, - otherwise treat *tight* as False. - The *tight* setting is retained for future autoscaling - until it is explicitly changed. - + If True, first set the margins to zero. Then, this argument is + forwarded to `autoscale_view` (regardless of its value); see the + description of its behavior there. """ if enable is None: scalex = True @@ -2381,17 +2379,31 @@ def autoscale_view(self, tight=None, scalex=True, scaley=True): """ Autoscale the view limits using the data limits. - You can selectively autoscale only a single axis, e.g., the xaxis by - setting *scaley* to *False*. The autoscaling preserves any - axis direction reversal that has already been done. - - If *tight* is *False*, the axis major locator will be used - to expand the view limits if rcParams['axes.autolimit_mode'] - is 'round_numbers'. Note that any margins that are in effect - will be applied first, regardless of whether *tight* is - *True* or *False*. Specifying *tight* as *True* or *False* - saves the setting as a private attribute of the Axes; specifying - it as *None* (the default) applies the previously saved value. + Parameters + ---------- + tight : bool or None + If *True*, only expand the axis limits using the margins. Note + that unlike for `autoscale`, ``tight=True`` does *not* set the + margins to zero. + + If *False* and :rc:`axes.autolimit_mode` is 'round_numbers', then + after expansion by the margins, further expand the axis limits + using the axis major locator. + + If None (the default), reuse the value set in the previous call to + `autoscale_view` (the initial value is False, but the default style + sets :rc:`axes.autolimit_mode` to 'data', in which case this + behaves like True). + + scalex : bool + Whether to autoscale the x axis (default is True). + + scaley : bool + Whether to autoscale the x axis (default is True). + + Notes + ----- + The autoscaling preserves any preexisting axis direction reversal. The data limits are not updated automatically when artist data are changed after the artist has been added to an Axes instance. In that diff --git a/matplotlibrc.template b/matplotlibrc.template index c06ec1f8f9c3..c5ed800c85ca 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -336,7 +336,7 @@ ## as opposed to the rest of this file. #axes.autolimit_mode : data ## How to scale axes limits to the data. ## Use "data" to use data limits, plus some margin - ## Use "round_number" move to the nearest "round" number + ## Use "round_numbers" move to the nearest "round" number #axes.xmargin : .05 ## x margin. See `axes.Axes.margins` #axes.ymargin : .05 ## y margin See `axes.Axes.margins` #polaraxes.grid : True ## display grid on polar axes