Skip to content

Update docs of GridSpec #15031

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
Aug 11, 2019
Merged

Update docs of GridSpec #15031

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
43 changes: 30 additions & 13 deletions lib/matplotlib/gridspec.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -232,38 +232,42 @@ def _normalize(key, size, axis): # Includes last index.

class GridSpec(GridSpecBase):
"""
Specifies the geometry of the grid that a subplot can be placed in.
A grid layout to place subplots within a figure.

The location of grid is determined by similar way as the SubplotParams.
The location of the grid cells is determined in a similar way to
`~.figure.SubplotParams` using *left*, *right*, *top*, *bottom*, *wspace*
and *hspace*.
"""
def __init__(self, nrows, ncols, figure=None,
left=None, bottom=None, right=None, top=None,
wspace=None, hspace=None,
width_ratios=None, height_ratios=None):
"""
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.

Parameters
----------
nrows, ncols : int
The number of rows and columns of the grid.

figure : `~.figure.Figure`, optional
Only used for constrained layout to create a proper layoutbox.
Copy link
Member Author

Choose a reason for hiding this comment

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

This is better than nothing, but still not too helpful.

@jklymak Maybe you have a better description?


left, right, top, bottom : float, optional
Extent of the subplots as a fraction of figure width or height.
Left cannot be larger than right, and bottom cannot be larger than
top.
top. If not given, the values will be inferred from a figure or
rcParams when necessary. See also `GridSpec.get_subplot_params`.
Copy link
Member

@story645 story645 Aug 11, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

i think the when necessary is extraneous

Copy link
Member Author

@timhoffm timhoffm Aug 11, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

What I wanted to express with that is that it is a delayed evaluation. In contrast to many other default fallbacks GridSpec.left stays None. The paradigm seems to be to use get_subplot_params which will resolve to the given alternatives.

Maybe "at usage time" or something would be better?

Copy link
Member

Choose a reason for hiding this comment

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

at run time or at draw time or when the figure is being rendered? Those are both a bit more jargony than I like but maybe closer to clearer?

Copy link
Member Author

Choose a reason for hiding this comment

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

Thanks. Chosen "at draw time" in #15106.


wspace : float, optional
The amount of width reserved for space between subplots,
expressed as a fraction of the average axis width.
If not given, the values will be inferred from a figure or
rcParams when necessary. See also `GridSpec.get_subplot_params`.

hspace : float, optional
The amount of height reserved for space between subplots,
expressed as a fraction of the average axis height.
If not given, the values will be inferred from a figure or
rcParams when necessary. See also `GridSpec.get_subplot_params`.

width_ratios : array-like of length *ncols*, optional
Defines the relative widths of the columns. Each column gets a
Expand All @@ -275,9 +279,6 @@ def __init__(self, nrows, ncols, figure=None,
relative height of ``height_ratios[i] / sum(height_ratios)``.
If not given, all rows will have the same height.

Notes
-----
See `~.figure.SubplotParams` for descriptions of the layout parameters.
"""
self.left = left
self.bottom = bottom
Expand Down Expand Up @@ -320,7 +321,12 @@ def __setstate__(self, state):

def update(self, **kwargs):
"""
Update the current values.
Update the subplot parameters of the grid.
Copy link
Member Author

@timhoffm timhoffm Aug 11, 2019 •
edited
Loading

Choose a reason for hiding this comment

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

I'm more specific which values to update.

But, there's also some position updating of some Axes happening, which I don't understand, so I'm still not describing that.

The last sentence

Values set to None use the rcParams value.

seems to be more like "Values set to None revert the parameter to the default (see get_subplot_params)"?

Unfortunately this behavior is also different from SubplotParams.update.


Parameters:
----------
left, right, top, bottom : float, optional
wspace, hspace : float, optional

Values set to None use the rcParams value.
"""
Expand Down Expand Up @@ -350,8 +356,13 @@ def update(self, **kwargs):

def get_subplot_params(self, figure=None):
"""
Return a dictionary of subplot layout parameters. The default
parameters are from rcParams unless a figure attribute is set.
Return the `~.SubplotParams` for the GridSpec.

In order of precedence the values are taken from

- non-*None* attributes of the GridSpec
- the provided *figure*
- :rc:`figure.subplot.*`
"""
if figure is None:
kw = {k: rcParams["figure.subplot."+k] for k in self._AllowedKeys}
Expand All @@ -364,6 +375,12 @@ def get_subplot_params(self, figure=None):
return subplotpars

def locally_modified_subplot_params(self):
"""
Return a list of the names of the subplot parameters explicitly set
in the GridSpec.

This is a subset of the attributes of `.SubplotParams`.
"""
return [k for k in self._AllowedKeys if getattr(self, k)]

def tight_layout(self, figure, renderer=None,
Expand Down