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

Improve docs on gridspec #14449

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jun 6, 2019
Merged

Improve docs on gridspec #14449

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 53 additions & 39 deletions 92 lib/matplotlib/gridspec.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,12 @@
"""
:mod:`~matplotlib.gridspec` is a module which specifies the location
of the subplot in the figure.

`GridSpec`
specifies the geometry of the grid that a subplot will be
placed. The number of rows and number of columns of the grid
need to be set. Optionally, the subplot layout parameters
(e.g., left, right, etc.) can be tuned.
r"""
:mod:`~matplotlib.gridspec` contains classes that help to layout multiple
`~axes.Axes` in a grid-like pattern within a figure.

`SubplotSpec`
specifies the location of the subplot in the given `GridSpec`.
The `GridSpec` specifies the overall grid structure. Individual cells within
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The classes including their first-line description are listed in the sphinx doc here anyway. There's no need to explicitly copy them here. Instead, just briefly describe the conceptual purpose.

the grid are referenced by `SubplotSpec`\s.

See the tutorial :ref:`sphx_glr_tutorials_intermediate_gridspec.py` for a
comprehensive usage guide.
"""

import copy
Expand Down Expand Up @@ -55,16 +51,16 @@ def __repr__(self):
)

def get_geometry(self):
'get the geometry of the grid, e.g., 2,3'
"""
Return a tuple containing the number of rows and columns in the grid.
"""
return self._nrows, self._ncols

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

def new_subplotspec(self, loc, rowspan=1, colspan=1):
"""
Create and return a SubplotSpec instance.
"""
"""Create and return a `.SubplotSpec` instance."""
loc1, loc2 = loc
subplotspec = self[loc1:loc1+rowspan, loc2:loc2+colspan]
return subplotspec
Expand All @@ -89,7 +85,7 @@ def get_height_ratios(self):

def get_grid_positions(self, fig, raw=False):
"""
return lists of bottom and top position of rows, left and
Return lists of bottom and top position of rows, left and
right positions of columns.

If raw=True, then these are all in units relative to the container
Expand Down Expand Up @@ -142,8 +138,7 @@ def get_grid_positions(self, fig, raw=False):
return fig_bottoms, fig_tops, fig_lefts, fig_rights

def __getitem__(self, key):
"""Create and return a SubplotSpec instance.
"""
"""Create and return a `.SubplotSpec` instance."""
nrows, ncols = self.get_geometry()

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

class GridSpec(GridSpecBase):
"""
A class that specifies the geometry of the grid that a subplot
will be placed. The location of grid is determined by similar way
as the SubplotParams.
"""
Specifies the geometry of the grid that a subplot can be placed in.

The location of grid is determined by similar way as the SubplotParams.
"""
def __init__(self, nrows, ncols, figure=None,
left=None, bottom=None, right=None, top=None,
wspace=None, hspace=None,
Expand Down Expand Up @@ -328,7 +322,7 @@ def tight_layout(self, figure, renderer=None,
fraction of the font-size.
h_pad, w_pad : float, optional
Padding (height/width) between edges of adjacent subplots.
Defaults to ``pad_inches``.
Defaults to *pad*.
rect : tuple of 4 floats, optional
(left, bottom, right, top) rectangle in normalized figure
coordinates that the whole subplots area (including labels) will
Expand Down Expand Up @@ -403,22 +397,33 @@ def get_subplot_params(self, figure=None):
wspace=wspace, hspace=hspace)

def get_topmost_subplotspec(self):
"""Get the topmost SubplotSpec instance associated with the subplot."""
"""
Return the topmost `.SubplotSpec` instance associated with the subplot.
"""
return self._subplot_spec.get_topmost_subplotspec()


class SubplotSpec:
"""Specifies the location of the subplot in the given `GridSpec`.
"""
Specifies the location of a subplot in a `GridSpec`.

def __init__(self, gridspec, num1, num2=None):
"""
.. note::

Likely, you'll never instantiate a `SubplotSpec` yourself. Instead you
will typically obtain one from a `GridSpec` using item-access.

Parameters
----------
gridspec : `~matplotlib.gridspec.GridSpec`
The GridSpec, which the subplot is referencing.
num1, num2 : int
The subplot will occupy the num1-th cell of the given
gridspec. If num2 is provided, the subplot will span between
num1-th cell and num2-th cell *inclusive*.

The index starts from 0.
"""
"""
def __init__(self, gridspec, num1, num2=None):
self._gridspec = gridspec
self.num1 = num1
self.num2 = num2
Expand Down Expand Up @@ -464,18 +469,19 @@ def get_gridspec(self):

def get_geometry(self):
"""
Get the subplot geometry (``n_rows, n_cols, start, stop``).
Return the subplot geometry as tuple ``(n_rows, n_cols, start, stop)``.

start and stop are the index of the start and stop of the
subplot.
The indices *start* and *stop* define the range of the subplot within
the `GridSpec`. *stop* is inclusive (i.e. for a single cell
``start == stop``).
"""
rows, cols = self.get_gridspec().get_geometry()
return rows, cols, self.num1, self.num2

def get_rows_columns(self):
"""
Get the subplot row and column numbers:
(``n_rows, n_cols, row_start, row_stop, col_start, col_stop``)
Return the subplot row and column numbers as a tuple
``(n_rows, n_cols, row_start, row_stop, col_start, col_stop)``.
"""
gridspec = self.get_gridspec()
nrows, ncols = gridspec.get_geometry()
Expand All @@ -484,7 +490,8 @@ def get_rows_columns(self):
return nrows, ncols, row_start, row_stop, col_start, col_stop

def get_position(self, figure, return_all=False):
"""Update the subplot position from ``figure.subplotpars``.
"""
Update the subplot position from ``figure.subplotpars``.
"""
gridspec = self.get_gridspec()
nrows, ncols = gridspec.get_geometry()
Expand All @@ -504,14 +511,20 @@ def get_position(self, figure, return_all=False):
return figbox

def get_topmost_subplotspec(self):
'get the topmost SubplotSpec instance associated with the subplot'
"""
Return the topmost `SubplotSpec` instance associated with the subplot.
"""
gridspec = self.get_gridspec()
if hasattr(gridspec, "get_topmost_subplotspec"):
return gridspec.get_topmost_subplotspec()
else:
return self

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

def subgridspec(self, nrows, ncols, **kwargs):
"""
Return a `.GridSpecFromSubplotSpec` that has this subplotspec as
Create a GridSpec within this subplot.

The created `.GridSpecFromSubplotSpec` will have this `SubplotSpec` as
a parent.

Parameters
Expand All @@ -536,12 +551,12 @@ def subgridspec(self, nrows, ncols, **kwargs):

Returns
-------
gridspec : `.GridSpec`
gridspec : `.GridSpecFromSubplotSpec`

Other Parameters
----------------
**kwargs
All other parameters are passed to `.GridSpec`.
All other parameters are passed to `.GridSpecFromSubplotSpec`.

See Also
--------
Expand All @@ -559,5 +574,4 @@ def subgridspec(self, nrows, ncols, **kwargs):
for i in range(3):
fig.add_subplot(gssub[0, i])
"""

return GridSpecFromSubplotSpec(nrows, ncols, self, **kwargs)
2 changes: 1 addition & 1 deletion 2 lib/matplotlib/tight_layout.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,7 @@ def get_tight_layout_figure(fig, axes_list, subplotspec_list, renderer,
fraction of the font size.
h_pad, w_pad : float
Padding (height/width) between edges of adjacent subplots. Defaults to
*pad_inches*.
*pad*.
rect : Tuple[float, float, float, float], optional
(left, bottom, right, top) rectangle in normalized figure coordinates
that the whole subplots area (including labels) will fit into.
Expand Down
Morty Proxy This is a proxified and sanitized view of the page, visit original site.