Menu
▾
▴
SF.net SVN: matplotlib:[7308] trunk/matplotlib/lib/matplotlib
|
From: <lee...@us...> - 2009-07-30 17:08:37
|
Revision: 7308
http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7308&view=rev
Author: leejjoon
Date: 2009-07-30 17:08:23 +0000 (Thu, 30 Jul 2009)
Log Message:
-----------
legend doc. update
Modified Paths:
--------------
trunk/matplotlib/lib/matplotlib/axes.py
trunk/matplotlib/lib/matplotlib/figure.py
trunk/matplotlib/lib/matplotlib/legend.py
trunk/matplotlib/lib/matplotlib/offsetbox.py
trunk/matplotlib/lib/matplotlib/pyplot.py
Modified: trunk/matplotlib/lib/matplotlib/axes.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/axes.py 2009-07-29 21:28:50 UTC (rev 7307)
+++ trunk/matplotlib/lib/matplotlib/axes.py 2009-07-30 17:08:23 UTC (rev 7308)
@@ -3906,31 +3906,66 @@
'center' 10
=============== =============
- If none of these are locations are suitable, loc can be a 2-tuple
- giving x,y in axes coords, ie::
- loc = 0, 1 # left top
- loc = 0.5, 0.5 # center
+ Users can specify any arbitrary location for the legend using the
+ *bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
+ of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
+ For example,
+
+ loc = 'upper right', bbox_to_anchor = (0.5, 0.5)
+ will place the legend so that the upper right corner of the legend at
+ the center of the axes.
+
+ The legend location can be specified in other coordinate, by using the
+ *bbox_transform* keyword.
+
+ The loc itslef can be a 2-tuple giving x,y of the lower-left corner of
+ the legend in axes coords (*bbox_to_anchor* is ignored).
+
+
Keyword arguments:
- *isaxes*: [ True | False ]
- Indicates that this is an axes legend
+ *prop*: [ None | FontProperties | dict ]
+ A :class:`matplotlib.font_manager.FontProperties`
+ instance. If *prop* is a dictionary, a new instance will be
+ created with *prop*. If *None*, use rc settings.
*numpoints*: integer
- The number of points in the legend line, default is 4
+ The number of points in the legend for line
- *prop*: [ None | FontProperties ]
- A :class:`matplotlib.font_manager.FontProperties`
- instance, or *None* to use rc settings.
+ *scatterpoints*: integer
+ The number of points in the legend for scatter plot
+ *scatteroffsets*: list of floats
+ a list of yoffsets for scatter symbols in legend
+
*markerscale*: [ None | scalar ]
The relative size of legend markers vs. original. If *None*, use rc
settings.
+ *fancybox*: [ None | False | True ]
+ if True, draw a frame with a round fancybox. If None, use rc
+
*shadow*: [ None | False | True ]
If *True*, draw a shadow behind legend. If *None*, use rc settings.
+ *ncol* : integer
+ number of columns. default is 1
+
+ *mode* : [ "expand" | None ]
+ if mode is "expand", the legend will be horizontally expanded
+ to fill the axes area (or *bbox_to_anchor*)
+
+ *bbox_to_anchor* : an instance of BboxBase or a tuple of 2 or 4 floats
+ the bbox that the legend will be anchored.
+
+ *bbox_transform* : [ an instance of Transform | None ]
+ the transform for the bbox. transAxes if None.
+
+ *title* : string
+ the legend title
+
Padding and spacing between various elements use following keywords
parameters. The dimensions of these values are given as a fraction
of the fontsize. Values from rcParams will be used if None.
@@ -3946,9 +3981,13 @@
columnspacing the spacing between columns
================ ==================================================================
+
**Example:**
.. plot:: mpl_examples/api/legend_demo.py
+
+ Also see :ref:`plotting-guide-legend`.
+
"""
if len(args)==0:
Modified: trunk/matplotlib/lib/matplotlib/figure.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/figure.py 2009-07-29 21:28:50 UTC (rev 7307)
+++ trunk/matplotlib/lib/matplotlib/figure.py 2009-07-30 17:08:23 UTC (rev 7308)
@@ -829,29 +829,60 @@
(0,0) is the left, bottom of the figure and 1,1 is the right,
top.
- The legend instance is returned. The following kwargs are supported
+ Keyword arguments:
- *loc*
- the location of the legend
- *numpoints*
- the number of points in the legend line
- *prop*
- a :class:`matplotlib.font_manager.FontProperties` instance
- *pad*
- the fractional whitespace inside the legend border
- *markerscale*
- the relative size of legend markers vs. original
- *shadow*
- if True, draw a shadow behind legend
- *labelsep*
- the vertical space between the legend entries
- *handlelen*
- the length of the legend lines
- *handletextsep*
- the space between the legend line and legend text
- *axespad*
- the border between the axes and legend edge
+ *prop*: [ None | FontProperties | dict ]
+ A :class:`matplotlib.font_manager.FontProperties`
+ instance. If *prop* is a dictionary, a new instance will be
+ created with *prop*. If *None*, use rc settings.
+ *numpoints*: integer
+ The number of points in the legend line, default is 4
+
+ *scatterpoints*: integer
+ The number of points in the legend line, default is 4
+
+ *scatteroffsets*: list of floats
+ a list of yoffsets for scatter symbols in legend
+
+ *markerscale*: [ None | scalar ]
+ The relative size of legend markers vs. original. If *None*, use rc
+ settings.
+
+ *fancybox*: [ None | False | True ]
+ if True, draw a frame with a round fancybox. If None, use rc
+
+ *shadow*: [ None | False | True ]
+ If *True*, draw a shadow behind legend. If *None*, use rc settings.
+
+ *ncol* : integer
+ number of columns. default is 1
+
+ *mode* : [ "expand" | None ]
+ if mode is "expand", the legend will be horizontally expanded
+ to fill the axes area (or *bbox_to_anchor*)
+
+ *title* : string
+ the legend title
+
+ Padding and spacing between various elements use following keywords
+ parameters. The dimensions of these values are given as a fraction
+ of the fontsize. Values from rcParams will be used if None.
+
+ ================ ==================================================================
+ Keyword Description
+ ================ ==================================================================
+ borderpad the fractional whitespace inside the legend border
+ labelspacing the vertical space between the legend entries
+ handlelength the length of the legend handles
+ handletextpad the pad between the legend handle and text
+ borderaxespad the pad between the axes and legend border
+ columnspacing the spacing between columns
+ ================ ==================================================================
+
+
+ **Example:**
+
.. plot:: mpl_examples/pylab_examples/figlegend_demo.py
"""
handles = flatten(handles)
Modified: trunk/matplotlib/lib/matplotlib/legend.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/legend.py 2009-07-29 21:28:50 UTC (rev 7307)
+++ trunk/matplotlib/lib/matplotlib/legend.py 2009-07-30 17:08:23 UTC (rev 7308)
@@ -126,13 +126,15 @@
================ ==================================================================
Keyword Description
================ ==================================================================
- loc a location code or a tuple of coordinates
- numpoints the number of points in the legend line
+ loc a location code
prop the font property
markerscale the relative size of legend markers vs. original
+ numpoints the number of points in the legend for line
+ scatterpoints the number of points in the legend for scatter plot
+ scatteryoffsets a list of yoffsets for scatter symbols in legend
fancybox if True, draw a frame with a round fancybox. If None, use rc
shadow if True, draw a shadow behind legend
- scatteryoffsets a list of yoffsets for scatter symbols in legend
+ ncol number of columns
borderpad the fractional whitespace inside the legend border
labelspacing the vertical space between the legend entries
handlelength the length of the legend handles
@@ -147,9 +149,14 @@
The dimensions of pad and spacing are given as a fraction of the
_fontsize. Values from rcParams will be used if None.
-bbox_to_anchor can be an instance of BboxBase(or its derivatives) or a
-tuple of 2 or 4 floats. See :meth:`set_bbox_to_anchor` for more
-detail.
+Users can specify any arbitrary location for the legend using the
+*bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
+of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
+See :meth:`set_bbox_to_anchor` for more detail.
+
+The legend location can be specified by setting *loc* with a tuple of
+2 floats, which is interpreted as the lower-left corner of the legend
+in the normalized axes coordinate.
"""
from matplotlib.axes import Axes # local import only to avoid circularity
from matplotlib.figure import Figure # local import only to avoid circularity
@@ -158,8 +165,13 @@
if prop is None:
self.prop=FontProperties(size=rcParams["legend.fontsize"])
+ elif isinstance(prop, dict):
+ self.prop=FontProperties(**prop)
+ if "size" not in prop:
+ self.prop.set_size(rcParams["legend.fontsize"])
else:
self.prop=prop
+
self._fontsize = self.prop.get_size_in_points()
propnames=['numpoints', 'markerscale', 'shadow', "columnspacing",
Modified: trunk/matplotlib/lib/matplotlib/offsetbox.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/offsetbox.py 2009-07-29 21:28:50 UTC (rev 7307)
+++ trunk/matplotlib/lib/matplotlib/offsetbox.py 2009-07-30 17:08:23 UTC (rev 7308)
@@ -833,6 +833,10 @@
if prop is None:
self.prop=FontProperties(size=rcParams["legend.fontsize"])
+ elif isinstance(prop, dict):
+ self.prop=FontProperties(**prop)
+ if "size" not in prop:
+ self.prop.set_size(rcParams["legend.fontsize"])
else:
self.prop = prop
Modified: trunk/matplotlib/lib/matplotlib/pyplot.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/pyplot.py 2009-07-29 21:28:50 UTC (rev 7307)
+++ trunk/matplotlib/lib/matplotlib/pyplot.py 2009-07-30 17:08:23 UTC (rev 7308)
@@ -438,7 +438,7 @@
.. seealso::
:func:`~matplotlib.pyplot.legend`
- For information about the location codes
+
"""
l = gcf().legend(handles, labels, loc, **kwargs)
draw_if_interactive()
@@ -6322,31 +6322,69 @@
'center' 10
=============== =============
-If none of these are locations are suitable, loc can be a 2-tuple
-giving x,y in axes coords, ie::
- loc = 0, 1 # left top
- loc = 0.5, 0.5 # center
+Users can specify any arbitrary location for the legend using the
+*bbox_to_anchor* keyword argument. bbox_to_anchor can be an instance
+of BboxBase(or its derivatives) or a tuple of 2 or 4 floats.
+For example, ::
+
+ loc = 'upper right', bbox_to_anchor = (0.5, 0.5)
+will place the legend so that the upper right corner of the legend at
+the center of the axes.
+
+The legend location can be specified in other coordinate, by using the
+*bbox_transform* keyword.
+
+The loc itslef can be a 2-tuple giving x,y of the lower-left corner of
+the legend in axes coords (*bbox_to_anchor* is ignored).
+
+
Keyword arguments:
*isaxes*: [ True | False ]
Indicates that this is an axes legend
+ *prop*: [ None | FontProperties | dict ]
+ A :class:`matplotlib.font_manager.FontProperties`
+ instance. If *prop* is a dictionary, a new instance will be
+ created with *prop*. If *None*, use rc settings.
+
*numpoints*: integer
- The number of points in the legend line, default is 4
+ The number of points in the legend for line
- *prop*: [ None | FontProperties ]
- A :class:`matplotlib.font_manager.FontProperties`
- instance, or *None* to use rc settings.
+ *scatterpoints*: integer
+ The number of points in the legend for scatter plot
+ *scatteroffsets*: list of floats
+ a list of yoffsets for scatter symbols in legend
+
*markerscale*: [ None | scalar ]
The relative size of legend markers vs. original. If *None*, use rc
settings.
+ *fancybox*: [ None | False | True ]
+ if True, draw a frame with a round fancybox. If None, use rc
+
*shadow*: [ None | False | True ]
If *True*, draw a shadow behind legend. If *None*, use rc settings.
+ *ncol* : integer
+ number of columns. default is 1
+
+ *mode* : [ "expand" | None ]
+ if mode is "expand", the legend will be horizontally expanded
+ to fill the axes area (or *bbox_to_anchor*)
+
+ *bbox_to_anchor* : an instance of BboxBase or a tuple of 2 or 4 floats
+ the bbox that the legend will be anchored.
+
+ *bbox_transform* : [ an instance of Transform | None ]
+ the transform for the bbox. transAxes if None.
+
+ *title* : string
+ the legend title
+
Padding and spacing between various elements use following keywords
parameters. The dimensions of these values are given as a fraction
of the fontsize. Values from rcParams will be used if None.
@@ -6362,9 +6400,14 @@
columnspacing the spacing between columns
================ ==================================================================
+
**Example:**
-.. plot:: mpl_examples/api/legend_demo.py"""
+.. plot:: mpl_examples/api/legend_demo.py
+
+Also see :ref:`plotting-guide-legend`.
+
+"""
ret = gca().legend(*args, **kwargs)
draw_if_interactive()
return ret
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|