diff --git a/lib/matplotlib/figure.py b/lib/matplotlib/figure.py index 683100657508..761bb04cab33 100644 --- a/lib/matplotlib/figure.py +++ b/lib/matplotlib/figure.py @@ -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. @@ -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() @@ -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: @@ -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) @@ -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)) @@ -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 -------- @@ -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 @@ -983,7 +1007,7 @@ 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) @@ -991,13 +1015,13 @@ 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 """ @@ -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. @@ -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 = [] @@ -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)