8000 Merge pull request #14449 from timhoffm/doc-gridspec · matplotlib/matplotlib@0536a66 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0536a66

Browse files
jklymakjklymak
authored
Merge pull request #14449 from timhoffm/doc-gridspec
Improve docs on gridspec
2 parents db2193c + eabe58b commit 0536a66

File tree

2 files changed

+54
-40
lines changed

2 files changed

+54
-40
lines changed

‎lib/matplotlib/gridspec.py

Lines changed: 53 additions & 39 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 that 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,
@@ -328,7 +322,7 @@ def tight_layout(self, figure, renderer=None,
328322
fraction of the font-size.
329323
h_pad, w_pad : float, optional
330324
Padding (height/width) between edges of adjacent subplots.
331-
Defaults to ``pad_inches``.
325+
Defaults to *pad*.
332326
rect : tuple of 4 floats, optional
333327
(left, bottom, right, top) rectangle in normalized figure
334328
coordinates that the whole subplots area (including labels) will
@@ -403,22 +397,33 @@ def get_subplot_params(self, figure=None):
403397
wspace=wspace, hspace=hspace)
404398

405399
def get_topmost_subplotspec(self):
406-
"""Get the topmost SubplotSpec instance associated with the subplot."""
400+
"""
401+
Return the topmost `.SubplotSpec` instance associated with the subplot.
402+
"""
407403
return self._subplot_spec.get_topmost_subplotspec()
408404

409405

410406
class SubplotSpec:
411-
"""Specifies the location of the subplot in the given `GridSpec`.
412407
"""
408+
Specifies the location of a subplot in a `GridSpec`.
413409
414-
def __init__(self, gridspec, num1, num2=None):
415-
"""
410+
.. note::
411+
412+
Likely, you'll never instantiate a `SubplotSpec` yourself. Instead you
413+
will typically obtain one from a `GridSpec` using item-access.
414+
415+
Parameters
416+
----------
417+
gridspec : `~matplotlib.gridspec.GridSpec`
418+
The GridSpec, which the subplot is referencing.
419+
num1, num2 : int
416420
The subplot will occupy the num1-th cell of the given
417421
gridspec. If num2 is provided, the subplot will span between
418422
num1-th cell and num2-th cell *inclusive*.
419423
420424
The index starts from 0.
421-
"""
425+
"""
426+
def __init__(self, gridspec, num1, num2=None):
422427
self._gridspec = gridspec
423428
self.num1 = num1
424429
self.num2 = num2
@@ -464,18 +469,19 @@ def get_gridspec(self):
464469

465470
def get_geometry(self):
466471
"""
467-
Get the subplot geometry (``n_rows, n_cols, start, stop``).
472+
Return the subplot geometry as tuple ``(n_rows, n_cols, start, stop)``.
468473
469-
start and stop are the index of the start and stop of the
470-
subplot.
474+
The indices *start* and *stop* define the range of the subplot within
475+
the `GridSpec`. *stop* is inclusive (i.e. for a single cell
476+
``start == stop``).
471477
"""
472478
rows, cols = self.get_gridspec().get_geometry()
473479
return rows, cols, self.num1, self.num2
474480

475481
def get_rows_columns(self):
476482
"""
477-
Get the subplot row and column numbers:
478-
(``n_rows, n_cols, row_start, row_stop, col_start, col_stop``)
483+
Return the subplot row and column numbers as a tuple
484+
``(n_rows, n_cols, row_start, row_stop, col_start, col_stop)``.
479485
"""
480486
gridspec = self.get_gridspec()
481487
nrows, ncols = gridspec.get_geometry()
@@ -484,7 +490,8 @@ def get_rows_columns(self):
484490
return nrows, ncols, row_start, row_stop, col_start, col_stop
485491

486492
def get_position(self, figure, return_all=False):
487-
"""Update the subplot position from ``figure.subplotpars``.
493+
"""
494+
Update the subplot position from ``figure.subplotpars``.
488495
"""
489496
gridspec = self.get_gridspec()
490497
nrows, ncols = gridspec.get_geometry()
@@ -504,14 +511,20 @@ def get_position(self, figure, return_all=False):
504511
return figbox
505512

506513
def get_topmost_subplotspec(self):
507-
'get the topmost SubplotSpec instance associated with the subplot'
514+
"""
515+
Return the topmost `SubplotSpec` instance associated with the subplot.
516+
"""
508517
gridspec = self.get_gridspec()
509518
if hasattr(gridspec, "get_topmost_subplotspec"):
510519
return gridspec.get_topmost_subplotspec()
511520
else:
512521
return self
513522

514523
def __eq__(self, other):
524+
"""
525+
Two SubplotSpecs are considered equal if they refer to the same
526+
position(s) in the same `GridSpec`.
527+
"""
515528
# other may not even have the attributes we are checking.
516529
return ((self._gridspec, self.num1, self.num2)
517530
== (getattr(other, "_gridspec", object()),
@@ -523,7 +536,9 @@ def __hash__(self):
523536

524537
def subgridspec(self, nrows, ncols, **kwargs):
525538
"""
526-
Return a `.GridSpecFromSubplotSpec` that has this subplotspec as
539+
Create a GridSpec within this subplot.
540+
541+
The created `.GridSpecFromSubplotSpec` will have this `SubplotSpec` as
527542
a parent.
528543
529544
Parameters
@@ -536,12 +551,12 @@ def subgridspec(self, nrows, ncols, **kwargs):
536551
537552
Returns
538553
-------
539-
gridspec : `.GridSpec`
554+
gridspec : `.GridSpecFromSubplotSpec`
540555
541556
Other Parameters
542557
----------------
543558
**kwargs
544-
All other parameters are passed to `.GridSpec`.
559+
All other parameters are passed to `.GridSpecFromSubplotSpec`.
545560
546561
See Also
547562
--------
@@ -559,5 +574,4 @@ def subgridspec(self, nrows, ncols, **kwargs):
559574
for i in range(3):
560575
fig.add_subplot(gssub[0, i])
561576
"""
562-
563577
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