8000 Backport PR #14449: Improve docs on gridspec · matplotlib/matplotlib@dd8654b · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit dd8654b

Browse files
jklymaktimhoffm
jklymak
authored and
timhoffm
committed
Backport PR #14449: Improve docs on gridspec
1 parent 3c20e9e commit dd8654b

File tree

2 files changed

+55
-41
lines changed

2 files changed

+55
-41
lines changed

‎lib/matplotlib/gridspec.py

Lines changed: 54 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,12 @@
1-
"""
2-
:mod:`~matplotlib.gridspec` is a module which specifies the location
3-
of the subplot in the figure.
4-
5-
`GridSpec`
6-
specifies the geometry of the grid that a subplot will be
7-
placed. The number of rows and number of columns of the grid
8-
need to be set. Optionally, the subplot layout parameters
9-
(e.g., left, right, etc.) can be tuned.
1+
r"""
2+
:mod:`~matplotlib.gridspec` contains classes that help to layout multiple
3+
`~axes.Axes` in a grid-like pattern within a figure.
104
11-
`SubplotSpec`
12-
specifies the location of the subplot in the given `GridSpec`.
5+
The `GridSpec` specifies the overall grid structure. Individual cells within
6+
the grid are referenced by `SubplotSpec`\s.
137
8+
See the tutorial :ref:`sphx_glr_tutorials_intermediate_gridspec.py` for a
9+
comprehensive usage guide.
1410
"""
1511

1612
import copy
@@ -55,16 +51,16 @@ def __repr__(self):
5551
)
5652

5753
def get_geometry(self):
58-
'get the geometry of the grid, e.g., 2,3'
54+
"""
55+
Return a tuple containing the number of rows and columns in the grid.
56+
"""
5957
return self._nrows, self._ncols
6058

6159
def get_subplot_params(self, figure=None, fig=None):
6260
pass
6361

6462
def new_subplotspec(self, loc, rowspan=1, colspan=1):
65-
"""
66-
Create and return a SubplotSpec instance.
67-
"""
63+
"""Create and return a `.SubplotSpec` instance."""
6864
loc1, loc2 = loc
6965
subplotspec = self[loc1:loc1+rowspan, loc2:loc2+colspan]
7066
return subplotspec
@@ -89,7 +85,7 @@ def get_height_ratios(self):
8985

9086
def get_grid_positions(self, fig, raw=False):
9187
"""
92-
return lists of bottom and top position of rows, left and
88+
Return lists of bottom and top position of rows, left and
9389
right positions of columns.
9490
9591
If raw=True, then these are all in units relative to the container
@@ -142,8 +138,7 @@ def get_grid_positions(self, fig, raw=False):
142138
return fig_bottoms, fig_tops, fig_lefts, fig_rights
143139

144140
def __getitem__(self, key):
145-
"""Create and return a SubplotSpec instance.
146-
"""
141+
"""Create and return a `.SubplotSpec` instance."""
147142
nrows, ncols = self.get_geometry()
148143

149144
def _normalize(key, size, axis): # Includes last index.
@@ -182,11 +177,10 @@ def _normalize(key, size, axis): # Includes last index.
182177

183178
class GridSpec(GridSpecBase):
184179
"""
185-
A class th E864 at specifies the geometry of the grid that a subplot
186-
will be placed. The location of grid is determined by similar way
187-
as the SubplotParams.
188-
"""
180+
Specifies the geometry of the grid that a subplot can be placed in.
189181
182+
The location of grid is determined by similar way as the SubplotParams.
183+
"""
190184
def __init__(self, nrows, ncols, figure=None,
191185
left=None, bottom=None, right=None, top=None,
192186
wspace=None, hspace=None,
@@ -329,7 +323,7 @@ def tight_layout(self, figure, renderer=None,
329323
fraction of the font-size.
330324
h_pad, w_pad : float, optional
331325
Padding (height/width) between edges of adjacent subplots.
332-
Defaults to ``pad_inches``.
326+
Defaults to *pad*.
333327
rect : tuple of 4 floats, optional
334328
(left, bottom, right, top) rectangle in normalized figure
335329
coordinates that the whole subplots area (including labels) will
@@ -404,22 +398,33 @@ def get_subplot_params(self, figure=None):
404398
wspace=wspace, hspace=hspace)
405399

406400
def get_topmost_subplotspec(self):
407-
"""Get the topmost SubplotSpec instance associated with the subplot."""
401+
"""
402+
Return the topmost `.SubplotSpec` instance associated with the subplot.
403+
"""
408404
return self._subplot_spec.get_topmost_subplotspec()
409405

410406

411-
class SubplotSpec(object):
412-
"""Specifies the location of the subplot in the given `GridSpec`.
407+
class SubplotSpec:
413408
"""
409+
Specifies the location of a subplot in a `GridSpec`.
414410
415-
def __init__(self, gridspec, num1, num2=None):
416-
"""
411+
.. note::
412+
413+
Likely, you'll never instantiate a `SubplotSpec` yourself. Instead you
414+
will typically obtain one from a `GridSpec` using item-access.
415+
416+
Parameters
417+
----------
418+
gridspec : `~matplotlib.gridspec.GridSpec`
419+
The GridSpec, which the subplot is referencing.
420+
num1, num2 : int
417421
The subplot will occupy the num1-th cell of the given
418422
gridspec. If num2 is provided, the subplot will span between
419423
num1-th cell and num2-th cell.
420424
421425
The index starts from 0.
422-
"""
426+
"""
427+
def __init__(self, gridspec, num1, num2=None):
423428
self._gridspec = gridspec
424429
self.num1 = num1
425430
self.num2 = num2
@@ -454,18 +459,19 @@ def get_gridspec(self):
454459

455460
def get_geometry(self):
456461
"""
457-
Get the subplot geometry (``n_rows, n_cols, start, stop``).
462+
Return the subplot geometry as tuple ``(n_rows, n_cols, start, stop)``.
458463
459-
start and stop are the index of the start and stop of the
460-
subplot.
464+
The indices *start* and *stop* define the range of the subplot within
465+
the `GridSpec`. *stop* is inclusive (i.e. for a single cell
466+
``start == stop``).
461467
"""
462468
rows, cols = self.get_gridspec().get_geometry()
463469
return rows, cols, self.num1, self.num2
464470

465471
def get_rows_columns(self):
466472
"""
467-
Get the subplot row and column numbers:
468-
(``n_rows, n_cols, row_start, row_stop, col_start, col_stop``)
473+
Return the subplot row and column numbers as a tuple
474+
``(n_rows, n_cols, row_start, row_stop, col_start, col_stop)``.
469475
"""
470476
gridspec = self.get_gridspec()
471477
nrows, ncols = gridspec.get_geometry()
@@ -478,7 +484,8 @@ def get_rows_columns(self):
478484
return nrows, ncols, row_start, row_stop, col_start, col_stop
479485

480486
def get_position(self, figure, return_all=False):
481-
"""Update the subplot position from ``figure.subplotpars``.
487+
"""
488+
Update the subplot position from ``figure.subplotpars``.
482489
"""
483490
gridspec = self.get_gridspec()
484491
nrows, ncols = gridspec.get_geometry()
@@ -500,14 +507,20 @@ def get_position(self, figure, return_all=False):
500507
return figbox
501508

502509
def get_topmost_subplotspec(self):
503-
'get the topmost SubplotSpec instance associated with the subplot'
510+
"""
511+
Return the topmost `SubplotSpec` instance associated with the subplot.
512+
"""
504513
gridspec = self.get_gridspec()
505514
if hasattr(gridspec, "get_topmost_subplotspec"):
506515
return gridspec.get_topmost_subplotspec()
507516
else:
508517
return self
509518

510519
def __eq__(self, other):
520+
"""
521+
Two SubplotSpecs are considered equal if they refer to the same
522+
position(s) in the same `GridSpec`.
523+
"""
511524
# other may not even have the attributes we are checking.
512525
return ((self._gridspec, self.num1, self.num2)
513526
== (getattr(other, "_gridspec", object()),
@@ -519,7 +532,9 @@ def __hash__(self):
519532

520533
def subgridspec(self, nrows, ncols, **kwargs):
521534
"""
522-
Return a `.GridSpecFromSubplotSpec` that has this subplotspec as
535+
Create a GridSpec within this subplot.
536+
537+
The created `.GridSpecFromSubplotSpec` will have this `SubplotSpec` as
523538
a parent.
524539
525540
Parameters
@@ -532,12 +547,12 @@ def subgridspec(self, nrows, ncols, **kwargs):
532547
533548
Returns
534549
-------
535-
gridspec : `.GridSpec`
550+
gridspec : `.GridSpecFromSubplotSpec`
536551
537552
Other Parameters
538553
----------------
539554
**kwargs
540-
All other parameters are passed to `.GridSpec`.
555+
All other parameters are passed to `.GridSpecFromSubplotSpec`.
541556
542557
See Also
543558
--------
@@ -555,5 +570,4 @@ def subgridspec(self, nrows, ncols, **kwargs):
555570
for i in range(3):
556571
fig.add_subplot(gssub[0, i])
557572
"""
558-
559573
return GridSpecFromSubplotSpec(nrows, ncols, self, **kwargs)

‎lib/matplotlib/tight_layout.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -281,7 +281,7 @@ def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
281281
fraction of the font size.
282282
h_pad, w_pad : float
283283
Padding (height/width) between edges of adjacent subplots. Defaults to
284-
*pad_inches*.
284+
*pad*.
285285
rect : Tuple[float, float, float, float], optional
286286
(left, bottom, right, top) rectangle in normalized figure coordinates
287287
that the whole subplots area (including labels) will fit into.

0 commit comments

Comments
 (0)
0