Skip to content

Commit 13415f9

Browse files
jklymakjklymak
committed
ENH: Constrained layout geometry manager
1 parent 4872b79 commit 13415f9

37 files changed

+4918
-65
lines changed

‎doc/api/api_changes/2017-09-29_JMK_constrained_layout_api.rst

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
API changes for ``constrained_layout``
2+
----------------------------------------
3+
4+
The new constrained_layout functionality has some minor (largely backwards-
5+
compatible) API changes. See
6+
:ref:`sphx_glr_tutorials_intermediate_constrainedlayout_guide.py` for
7+
more details on this functionality.
8+
9+
This requires a new dependency on kiwisolver_.
10+
11+
_https://github.com/nucleic/kiwi
12+
13+
kwarg ``fig`` deprectated in `.GridSpec.get_subplot_params`
14+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15+
16+
Use ``figure`` instead of ``fig``, which is now deprecated.

‎doc/users/next_whats_new/constrained_layout.rst

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
Constrained Layout Manager
2+
---------------------------
3+
4+
.. warning::
5+
6+
Constrained Layout is **experimental**. The
7+
behaviour and API are subject to change, or the whole functionality
8+
may be removed without a deprecation period.
9+
10+
11+
A new method to automatically decide spacing between subplots and their
12+
organizing ``GridSpec`` instances has been added. It is meant to
13+
replace the venerable ``tight_layout`` method. It is invoked via
14+
a new ``constrained_layout=True`` kwarg to
15+
`~.figure.Figure` or `~.figure.subplots`.
16+
17+
There are new ``rcParams`` for this package, and spacing can be
18+
more finely tuned with the new `~.set_constrained_layout_pads`.
19+
20+
Features include:
21+
22+
- Automatic spacing for subplots with a fixed-size padding in inches around
23+
subplots and all their decorators, and space between as a fraction
24+
of subplot size between subplots.
25+
- Spacing for `~.figure.suptitle`, and colorbars that are attached to
26+
more than one axes.
27+
- Nested `~.GridSpec` layouts using `~.GridSpecFromSubplotSpec`.
28+
29+
For more details and capabilities please see the new tutorial:
30+
:doc:`/tutorials/intermediate/constrainedlayout_guide`
31+
32+
Note the new API to access this:
33+
34+
New ``plt.figure`` and ``plt.subplots`` kwarg: ``constrained_layout``
35+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
36+
37+
:meth:`~matplotlib.pyplot.figure` and :meth:`~matplotlib.pyplot.subplots`
38+
can now be called with ``constrained_layout=True`` kwarg to enable
39+
constrained_layout.
40+
41+
New ``ax.set_position`` behaviour
42+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
43+
44+
:meth:`~matplotlib.axes.set_position` now makes the specified axis no
45+
longer responsive to ``constrained_layout``, consistent with the idea that the
46+
user wants to place an axis manually.
47+
48+
Internally, this means that old ``ax.set_position`` calls *inside* the library
49+
are changed to private ``ax._set_position`` calls so that
50+
``constrained_layout`` will still work with these axes.
51+
52+
New ``figure`` kwarg for ``GridSpec``
53+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
In order to facilitate ``constrained_layout``, ``GridSpec`` now accepts a
56+
``figure`` keyword. This is backwards compatible, in that not supplying this
57+
will simply cause ``constrained_layout`` to not operate on the subplots
58+
orgainzed by this ``GridSpec`` instance. Routines that use ``GridSpec`` (e.g.
59+
``fig.subplots``) have been modified to pass the figure to ``GridSpec``.

0 commit comments

Comments
 (0)