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 0536a66

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

File tree

Expand file treeCollapse file tree

2 files changed

+54
-40
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+54
-40
lines changed

‎lib/matplotlib/gridspec.py

Copy file name to clipboardExpand all lines: lib/matplotlib/gridspec.py
+53-39Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/tight_layout.py
+1-1Lines 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)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.