8000 Merge pull request #10666 from timhoffm/doc-figure-part-2 · matplotlib/matplotlib@5df8380 · GitHub
[go: up one dir, main page]
Skip to content

Commit 5df8380

Browse files
dstansbydstansby
authored
Merge pull request #10666 from timhoffm/doc-figure-part-2
More figure-related doc updates
2 parents 21c4f9e + 5e00f69 commit 5df8380

File tree

1 file changed

+100
-56
lines changed

1 file changed

+100
-56
lines changed

‎lib/matplotlib/figure.py‎

Lines changed: 100 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -62,8 +62,8 @@ def _stale_figure_callback(self, val):
6262

6363
class AxesStack(Stack):
6464
"""
65-
Specialization of the Stack to handle all tracking of Axes in a Figure.
66-
This stack stores ``key, (ind, axes)`` pairs, where:
65+
Specialization of the `.Stack` to handle all tracking of `.Axes` in a
66+
`.Figure`. This stack stores ``key, (ind, axes)`` pairs, where:
6767
6868
* **key** should be a hash of the args and kwargs
6969
used in generating the Axes.
@@ -81,7 +81,7 @@ def __init__(self):
8181

8282
def as_list(self):
8383
"""
84-
Return a list of the Axes instances that have been added to the figure
84+
Return a list of the Axes instances that have been added to the figure.
8585
"""
8686
ia_list = [a for k, a in self._elements]
8787
ia_list.sort()
@@ -90,7 +90,7 @@ def as_list(self):
9090
def get(self, key):
9191
"""
9292
Return the Axes instance that was added with *key*.
93-
If it is not present, return None.
93+
If it is not present, return *None*.
9494
"""
9595
item = dict(self._elements).get(key)
9696
if item is None:
@@ -689,31 +689,55 @@ def suptitle(self, t, **kwargs):
689689
"""
690690
Add a centered title to the figure.
691691
692-
kwargs are :class:`matplotlib.text.Text` properties. Using figure
693-
coordinates, the defaults are:
692+
Parameters
693+
----------
694+
t : str
695+
The title text.
696+
697+
x : float, default 0.5
698+
The x location of the text in figure coordinates.
699+
700+
y : float, default 0.98
701+
The y location of the text in figure coordinates.
702+
703+
horizontalalignment, ha : {'center', 'left', right'}, default: 'center'
704+
The horizontal alignment of the text.
694705
695-
x : 0.5
696-
The x location of the text in figure coords
706+
verticalalignment, va : {'top', 'center', 'bottom', 'baseline'}, \
707+
default: 'top'
708+
The vertical alignment of the text.
697709
698-
y : 0.98
699-
The y location of the text in figure coords
710+
fontsize, size : default: :rc:`figure.titlesize`
711+
The font size of the text. See `.Text.set_size` for possible
712+
values.
700713
701-
horizontalalignment : 'center'
702-
The horizontal alignment of the text
714+
fontweight, weight : default: :rc:`figuretitleweight`
715+
The font weight of the text. See `.Text.set_weight` for possible
716+
values.
703717
704-
verticalalignment : 'top'
705-
The vertical alignment of the text
706718
707-
If the `fontproperties` keyword argument is given then the
708-
rcParams defaults for `fontsize` (`figure.titlesize`) and
709-
`fontweight` (`figure.titleweight`) will be ignored in favour
710-
of the `FontProperties` defaults.
719+
Returns
720+
-------
721+
text
722+
The `.Text` instance of the title.
711723
712-
A :class:`matplotlib.text.Text` instance is returned.
713724
714-
Example::
725+
Other Parameters
726+
----------------
727+
fontproperties : None or dict, optional
728+
A dict of font properties. If *fontproperties* is given the
729+
default values for font size and weight are taken from the
730+
`FontProperties` defaults. :rc:`figure.titlesize` and
731+
:rc:`figure.titleweight` are ignored in this case.
715732
716-
fig.suptitle('this is the figure title', fontsize=12)
733+
**kwargs
734+
Additional kwargs are :class:`matplotlib.text.Text` properties.
735+
736+
737+
Examples
738+
--------
739+
740+
>>> fig.suptitle('This is the figure title', fontsize=12)
717741
"""
718742
x = kwargs.pop('x', 0.5)
719743
y = kwargs.pop('y', 0.98)
@@ -871,9 +895,9 @@ def figimage(self, X, xo=0, yo=0, alpha=None, norm=None, cmap=None,
871895
return im
872896

873897
def set_size_inches(self, w, h=None, forward=True):
874-
"""Set the figure size in inches (1in == 2.54cm)
898+
"""Set the figure size in inches.
875899
876-
Usage ::
900+
Call signatures::
877901
878902
fig.set_size_inches(w, h) # OR
879903
fig.set_size_inches((w, h))
@@ -882,7 +906,7 @@ def set_size_inches(self, w, h=None, forward=True):
882906
automatically updated; e.g., you can resize the figure window
883907
from the shell
884908
885-
ACCEPTS: a w, h tuple with w, h in inches
909+
ACCEPTS: a (w, h) tuple with w, h in inches
886910
887911
See Also
888912
--------
@@ -967,9 +991,9 @@ def set_facecolor(self, color):
967991

968992
def set_dpi(self, val):
969993
"""
970-
Set the dots-per-inch of the figure.
994+
Set the resolution of the figure in dots-per-inch.
971995
972-
ACCEPTS: float
996+
.. ACCEPTS: float
973997
"""
974998
self.dpi = val
975999
self.stale = True
@@ -978,21 +1002,21 @@ def set_figwidth(self, val, forward=True):
9781002
"""
9791003
Set the width of the 67DE figure in inches.
9801004
981-
ACCEPTS: float
1005+
.. ACCEPTS: float
9821006
"""
9831007
self.set_size_inches(val, self.get_figheight(), forward=forward)
9841008

9851009
def set_figheight(self, val, forward=True):
9861010
"""
9871011
Set the height of the figure in inches.
9881012
989-
ACCEPTS: float
1013+
.. ACCEPTS: float
9901014
"""
9911015
self.set_size_inches(self.get_figwidth(), val, forward=forward)
9921016

9931017
def set_frameon(self, b):
9941018
"""
995-
Set whether the figure frame (background) is displayed or invisible
1019+
Set whether the figure frame (background) is displayed or invisible.
9961020
9971021
ACCEPTS: boolean
9981022
"""
@@ -2094,7 +2118,7 @@ def subplots_adjust(self, *args, **kwargs):
20942118
Call signature::
20952119
20962120
subplots_adjust(left=None, bottom=None, right=None, top=None,
2097-
wspace=None, hspace=None)
2121+
wspace=None, hspace=None)
20982122
20992123
Update the :class:`SubplotParams` with *kwargs* (defaulting to rc when
21002124
*None*) and update the subplot locations.
@@ -2195,8 +2219,8 @@ def get_tightbbox(self, renderer):
21952219
"""
21962220
Return a (tight) bounding box of the figure in inches.
21972221
2198-
It only accounts axes title, axis labels, and axis
2199-
ticklabels. Needs improvement.
2222+
Currently, this takes only axes title, axis labels, and axis
2223+
ticklabels into account. Needs improvement.
22002224
"""
22012225

22022226
bb = []
@@ -2448,30 +2472,50 @@ def align_labels(self, axs=None):
24482472

24492473
def figaspect(arg):
24502474
"""
2451-
Create a figure with specified aspect ratio. If *arg* is a number,
2452-
use that aspect ratio. If *arg* is an array, figaspect will
2453-
determine the width and height for a figure that would fit array
2454-
preserving aspect ratio. The figure width, height in inches are
2455-
returned. Be sure to create an axes with equal with and height,
2456-
e.g.,
2457-
2458-
Example usage::
2459-
2460-
# make a figure twice as tall as it is wide
2461-
w, h = figaspect(2.)
2462-
fig = Figure(figsize=(w,h))
2463-
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
2464-
ax.imshow(A, **kwargs)
2465-
2466-
2467-
# make a figure with the proper aspect for an array
2468-
A = rand(5,3)
2469-
w, h = figaspect(A)
2470-
fig = Figure(figsize=(w,h))
2471-
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
2472-
ax.imshow(A, **kwargs)
2473-
2474-
Thanks to Fernando Perez for this function
2475+
Calculate the width and height for a figure with a specified aspect ratio.
2476+
2477+
While the height is taken from :rc:`figure.figsize`, the width is
2478+
adjusted to match the desired aspect ratio. Additionally, it is ensured
2479+
that the width is in the range [4., 16.] and the height is in the range
2480+
[2., 16.]. If necessary, the default height is adjusted to ensure this.
2481+
2482+
Parameters
2483+
----------
2484+
arg : scalar or 2d array
2485+
If a scalar, this defines the aspect ratio (i.e. the ratio height /
2486+
width).
2487+
In case of an array the aspect ratio is number of rows / number of
2488+
columns, so that the array could be fitted in the figure undistorted.
2489+
2490+
Returns
2491+
-------
2492+
width, height
2493+
The figure size in inches.
2494+
2495+
Notes
2496+
-----
2497+
If you want to create an axes within the figure, that still presevers the
2498+
aspect ratio, be sure to create it with equal width and height. See
2499+
examples below.
2500+
2501+
Thanks to Fernando Perez for this function.
2502+
2503+
Examples
2504+
--------
2505+
Make a figure twice as tall as it is wide::
2506+
2507+
w, h = figaspect(2.)
2508+
fig = Figure(figsize=(w, h))
2509+
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
2510+
ax.imshow(A, **kwargs)
2511+
2512+
Make a figure with the proper aspect for an array::
2513+
2514+
A = rand(5,3)
2515+
w, h = figaspect(A)
2516+
fig = Figure(figsize=(w, h))
2517+
ax = fig.add_axes([0.1, 0.1, 0.8, 0.8])
2518+
ax.imshow(A, **kwargs)
24752519
"""
24762520

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

0 commit comments

Comments
 (0)
0