Skip to content

More figure-related doc updates #10666

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
Mar 5, 2018
Merged

More figure-related doc updates #10666

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
156 changes: 100 additions & 56 deletions lib/matplotlib/figure.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ def _stale_figure_callback(self, val):

class AxesStack(Stack):
"""
Specialization of the Stack to handle all tracking of Axes in a Figure.
This stack stores ``key, (ind, axes)`` pairs, where:
Specialization of the `.Stack` to handle all tracking of `.Axes` in a
`.Figure`. This stack stores ``key, (ind, axes)`` pairs, where:

* **key** should be a hash of the args and kwargs
used in generating the Axes.
Expand All @@ -81,7 +81,7 @@ def __init__(self):

def as_list(self):
"""
Return a list of the Axes instances that have been added to the figure
Return a list of the Axes instances that have been added to the figure.
"""
ia_list = [a for k, a in self._elements]
ia_list.sort()
Expand All @@ -90,7 +90,7 @@ def as_list(self):
def get(self, key):
"""
Return the Axes instance that was added with *key*.
If it is not present, return None.
If it is not present, return *None*.
"""
item = dict(self._elements).get(key)
if item is None:
Expand Down Expand Up @@ -694,31 +694,55 @@ def suptitle(self, t, **kwargs):
"""
Add a centered title to the figure.

kwargs are :class:`matplotlib.text.Text` properties. Using figure
coordinates, the defaults are:
Parameters
----------
t : str
The title text.

x : float, default 0.5
The x location of the text in figure coordinates.

y : float, default 0.98
The y location of the text in figure coordinates.

horizontalalignment, ha : {'center', 'left', right'}, default: 'center'
The horizontal alignment of the text.

x : 0.5
The x location of the text in figure coords
verticalalignment, va : {'top', 'center', 'bottom', 'baseline'}, \
default: 'top'
The vertical alignment of the text.

y : 0.98
The y location of the text in figure coords
fontsize, size : default: :rc:`figure.titlesize`
The font size of the text. See `.Text.set_size` for possible
values.

horizontalalignment : 'center'
The horizontal alignment of the text
fontweight, weight : default: :rc:`figuretitleweight`
The font weight of the text. See `.Text.set_weight` for possible
values.

verticalalignment : 'top'
The vertical alignment of the text

If the `fontproperties` keyword argument is given then the
rcParams defaults for `fontsize` (`figure.titlesize`) and
`fontweight` (`figure.titleweight`) will be ignored in favour
of the `FontProperties` defaults.
Returns
-------
text
The `.Text` instance of the title.

A :class:`matplotlib.text.Text` instance is returned.

Example::
Other Parameters
----------------
fontproperties : None or dict, optional
A dict of font properties. If *fontproperties* is given the
default values for font size and weight are taken from the
`FontProperties` defaults. :rc:`figure.titlesize` and
:rc:`figure.titleweight` are ignored in this case.

fig.suptitle('this is the figure title', fontsize=12)
**kwargs
Additional kwargs are :class:`matplotlib.text.Text` properties.


Examples
--------

>>> fig.suptitle('This is the figure title', fontsize=12)
"""
x = kwargs.pop('x', 0.5)
y = kwargs.pop('y', 0.98)
Expand Down Expand Up @@ -876,9 +900,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
return im

def set_size_inches(self, w, h=None, forward=True):
"""Set the figure size in inches (1in == 2.54cm)
"""Set the figure size in inches.

Usage ::
Call signatures::

fig.set_size_inches(w, h) # OR
fig.set_size_inches((w, h))
Expand All @@ -887,7 +911,7 @@ def set_size_inches(self, w, h=None, forward=True):
automatically updated; e.g., you can resize the figure window
from the shell

ACCEPTS: a w, h tuple with w, h in inches
ACCEPTS: a (w, h) tuple with w, h in inches

See Also
--------
Expand Down Expand Up @@ -972,9 +996,9 @@ def set_facecolor(self, color):

def set_dpi(self, val):
"""
Set the dots-per-inch of the figure.
Set the resolution of the figure in dots-per-inch.

ACCEPTS: float
.. ACCEPTS: float
"""
self.dpi = val
self.stale = True
Expand All @@ -983,21 +1007,21 @@ def set_figwidth(self, val, forward=True):
"""
Set the width of the figure in inches.

ACCEPTS: float
.. ACCEPTS: float
"""
self.set_size_inches(val, self.get_figheight(), forward=forward)

def set_figheight(self, val, forward=True):
"""
Set the height of the figure in inches.

ACCEPTS: float
.. ACCEPTS: float
"""
self.set_size_inches(self.get_figwidth(), val, forward=forward)

def set_frameon(self, b):
"""
Set whether the figure frame (background) is displayed or invisible
Set whether the figure frame (background) is displayed or invisible.

ACCEPTS: boolean
"""
Expand Down Expand Up @@ -2093,7 +2117,7 @@ def subplots_adjust(self, *args, **kwargs):
Call signature::

subplots_adjust(left=None, bottom=None, right=None, top=None,
wspace=None, hspace=None)
wspace=None, hspace=None)

Update the :class:`SubplotParams` with *kwargs* (defaulting to rc when
*None*) and update the subplot locations.
Expand Down Expand Up @@ -2194,8 +2218,8 @@ def get_tightbbox(self, renderer):
"""
Return a (tight) bounding box of the figure in inches.

It only accounts axes title, axis labels, and axis
ticklabels. Needs improvement.
Currently, this takes only axes title, axis labels, and axis
ticklabels into account. Needs improvement.
"""

bb = []
Expand Down Expand Up @@ -2447,30 +2471,50 @@ def align_labels(self, axs=None):

def figaspect(arg):
"""
Create a figure with specified aspect ratio. If *arg* is a number,
use that aspect ratio. If *arg* is an array, figaspect will
determine the width and height for a figure that would fit array
preserving aspect ratio. The figure width, height in inches are
returned. Be sure to create an axes with equal with and height,
e.g.,

Example usage::

# make a figure twice as tall as it is wide
w, h = figaspect(2.)
fig = Figure(figsize=(w,h))
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
ax.imshow(A, **kwargs)


# make a figure with the proper aspect for an array
A = rand(5,3)
w, h = figaspect(A)
fig = Figure(figsize=(w,h))
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
ax.imshow(A, **kwargs)

Thanks to Fernando Perez for this function
Calculate the width and height for a figure with a specified aspect ratio.

While the height is taken from :rc:`figure.figsize`, the width is
adjusted to match the desired aspect ratio. Additionally, it is ensured
that the width is in the range [4., 16.] and the height is in the range
[2., 16.]. If necessary, the default height is adjusted to ensure this.

Parameters
----------
arg : scalar or 2d array
If a scalar, this defines the aspect ratio (i.e. the ratio height /
width).
In case of an array the aspect ratio is number of rows / number of
columns, so that the array could be fitted in the figure undistorted.

Returns
-------
width, height
The figure size in inches.

Notes
-----
If you want to create an axes within the figure, that still presevers the
aspect ratio, be sure to create it with equal width and height. See
examples below.

Thanks to Fernando Perez for this function.

Examples
--------
Make a figure twice as tall as it is wide::

w, h = figaspect(2.)
fig = Figure(figsize=(w, h))
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
ax.imshow(A, **kwargs)

Make a figure with the proper aspect for an array::

A = rand(5,3)
w, h = figaspect(A)
fig = Figure(figsize=(w, h))
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
ax.imshow(A, **kwargs)
"""

isarray = hasattr(arg, 'shape') and not np.isscalar(arg)
Expand Down