matplotlib-checkins Mailing List for matplotlib

Revision: 7310
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7310&view=rev
Author: evilguru
Date: 2009年07月30日 21:50:10 +0000 (2009年7月30日)
Log Message:
-----------
Revert r7307 to the mathtex branch after a dicussion on the mailing list.
Modified Paths:
--------------
 branches/mathtex/setup.py
 branches/mathtex/setupext.py
Modified: branches/mathtex/setup.py
===================================================================
--- branches/mathtex/setup.py	2009年07月30日 19:32:15 UTC (rev 7309)
+++ branches/mathtex/setup.py	2009年07月30日 21:50:10 UTC (rev 7310)
@@ -42,8 +42,7 @@
 check_for_qt, check_for_qt4, check_for_cairo, \
 check_provide_pytz, check_provide_dateutil,\
 check_for_dvipng, check_for_ghostscript, check_for_latex, \
- check_for_pdftops, check_for_datetime, options, build_png, \
- check_provide_mathtex, build_mathtex
+ check_for_pdftops, check_for_datetime, options, build_png
 #import distutils.sysconfig
 
 # jdh
@@ -129,9 +128,6 @@
 if has_libpng and options['build_agg'] or options['build_image']:
 build_png(ext_modules, packages)
 
-if has_libpng and options['provide_mathtex'] and check_provide_mathtex():
- build_mathtex(ext_modules, packages, package_data)
-
 if options['build_windowing'] and sys.platform=='win32':
 build_windowing(ext_modules, packages)
 
Modified: branches/mathtex/setupext.py
===================================================================
--- branches/mathtex/setupext.py	2009年07月30日 19:32:15 UTC (rev 7309)
+++ branches/mathtex/setupext.py	2009年07月30日 21:50:10 UTC (rev 7310)
@@ -98,7 +98,6 @@
 'verbose': False,
 'provide_pytz': 'auto',
 'provide_dateutil': 'auto',
- 'provide_mathtex' : 'auto',
 'build_agg': True,
 'build_gtk': 'auto',
 'build_gtkagg': 'auto',
@@ -127,10 +126,6 @@
 "dateutil")
 except: options['provide_dateutil'] = 'auto'
 
- try: options['provide_mathtex'] = config.getboolean("provide_packages",
- "mathtex")
- except: options['provide_mathtex'] = 'auto'
-
 try: options['build_gtk'] = config.getboolean("gui_support", "gtk")
 except: options['build_gtk'] = 'auto'
 
@@ -391,14 +386,6 @@
 print_status("datetime", "present, version unknown")
 return True
 
-def check_provide_mathtex():
- try:
- import mathtex
- except ImportError:
- print_status("mathtex", "matplotlib will provide")
- return True
- return False
-
 def check_provide_pytz(hasdatetime=True):
 if hasdatetime and (options['provide_pytz'] is True):
 print_status("pytz", "matplotlib will provide")
@@ -558,7 +545,7 @@
 else:
 add_base_flags(module)
 module.libraries.append('z')
-
+ 
 # put this last for library link order
 module.libraries.extend(std_libs)
 
@@ -1105,11 +1092,6 @@
 ext_modules.append(module)
 BUILT_FT2FONT = True
 
-def build_mathtex(ext_modules, packages, package_data):
- packages.append('mathtex/mathtex')
- packages.append('mathtex/mathtex.backends')
- package_data['mathtex'] = ['lib/mathtex/data/fonts/*.ttf']
-
 def build_ttconv(ext_modules, packages):
 global BUILT_TTCONV
 if BUILT_TTCONV: return # only build it if you you haven't already
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 7309
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7309&view=rev
Author: efiring
Date: 2009年07月30日 19:32:15 +0000 (2009年7月30日)
Log Message:
-----------
User-generated colormaps are handled more easily.
Modified Paths:
--------------
 trunk/matplotlib/CHANGELOG
 trunk/matplotlib/doc/api/api_changes.rst
 trunk/matplotlib/examples/pylab_examples/custom_cmap.py
 trunk/matplotlib/lib/matplotlib/cm.py
 trunk/matplotlib/lib/matplotlib/image.py
 trunk/matplotlib/lib/matplotlib/pyplot.py
Modified: trunk/matplotlib/CHANGELOG
===================================================================
--- trunk/matplotlib/CHANGELOG	2009年07月30日 17:08:23 UTC (rev 7308)
+++ trunk/matplotlib/CHANGELOG	2009年07月30日 19:32:15 UTC (rev 7309)
@@ -1,3 +1,7 @@
+2009年07月30日 Add set_cmap and register_cmap, and improve get_cmap,
+ to provide convenient handling of user-generated
+ colormaps. - EF
+
 2009年07月28日 Quiver speed improved, thanks to tip by Ray Speth. -EF
 
 2009年07月27日 Simplify argument handling code for plot method. -EF
Modified: trunk/matplotlib/doc/api/api_changes.rst
===================================================================
--- trunk/matplotlib/doc/api/api_changes.rst	2009年07月30日 17:08:23 UTC (rev 7308)
+++ trunk/matplotlib/doc/api/api_changes.rst	2009年07月30日 19:32:15 UTC (rev 7309)
@@ -21,6 +21,11 @@
 Changes beyond 0.98.x
 =====================
 
+* User-generated colormaps can now be added to the set recognized
+ by :func:`matplotlib.cm.get_cmap`. Colormaps can be made the
+ default and applied to the current image using
+ :func:`matplotlib.pyplot.set_cmap`.
+
 * changed use_mrecords default to False in mlab.csv2rec since this is
 partially broken
 
Modified: trunk/matplotlib/examples/pylab_examples/custom_cmap.py
===================================================================
--- trunk/matplotlib/examples/pylab_examples/custom_cmap.py	2009年07月30日 17:08:23 UTC (rev 7308)
+++ trunk/matplotlib/examples/pylab_examples/custom_cmap.py	2009年07月30日 19:32:15 UTC (rev 7309)
@@ -103,11 +103,25 @@
 (1.0, 0.0, 0.0))
 }
 
+# Now we will use this example to illustrate 3 ways of
+# handling custom colormaps.
+# First, the most direct and explicit:
 
 blue_red1 = LinearSegmentedColormap('BlueRed1', cdict1)
+
+# Second, create the map explicitly and register it.
+# Like the first method, this method works with any kind
+# of Colormap, not just
+# a LinearSegmentedColormap:
+
 blue_red2 = LinearSegmentedColormap('BlueRed2', cdict2)
-blue_red3 = LinearSegmentedColormap('BlueRed3', cdict3)
+plt.register_cmap(cmap=blue_red2)
 
+# Third, for LinearSegmentedColormap only,
+# leave everything to register_cmap:
+
+plt.register_cmap(name='BlueRed3', data=cdict3) # optional lut kwarg
+
 x = np.arange(0, np.pi, 0.1)
 y = np.arange(0, 2*np.pi, 0.1)
 X, Y = np.meshgrid(x,y)
@@ -121,13 +135,33 @@
 plt.colorbar()
 
 plt.subplot(1,3,2)
-plt.imshow(Z, interpolation='nearest', cmap=blue_red2)
+cmap = plt.get_cmap('BlueRed2')
+plt.imshow(Z, interpolation='nearest', cmap=cmap)
 plt.colorbar()
 
+# Now we will set the third cmap as the default. One would
+# not normally do this in the middle of a script like this;
+# it is done here just to illustrate the method.
+
+plt.rcParams['image.cmap'] = 'BlueRed3'
+
+# Also see below for an alternative, particularly for
+# interactive use.
+
 plt.subplot(1,3,3)
-plt.imshow(Z, interpolation='nearest', cmap=blue_red3)
+plt.imshow(Z, interpolation='nearest')
 plt.colorbar()
 
+# Or as yet another variation, we could replace the rcParams
+# specification *before* the imshow with the following *after*
+# imshow:
+#
+# plt.set_cmap('BlueRed3')
+#
+# This sets the new default *and* sets the colormap of the last
+# image-like item plotted via pyplot, if any.
+
+
 plt.suptitle('Custom Blue-Red colormaps')
 
 plt.show()
Modified: trunk/matplotlib/lib/matplotlib/cm.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/cm.py	2009年07月30日 17:08:23 UTC (rev 7308)
+++ trunk/matplotlib/lib/matplotlib/cm.py	2009年07月30日 19:32:15 UTC (rev 7309)
@@ -9,16 +9,79 @@
 import matplotlib.cbook as cbook
 from matplotlib._cm import *
 
+# Dictionary for user-registered colormaps:
+cmap_d = dict()
 
+# Using this second dictionary allows us to handle any
+# Colormap instance; the built-in datad is only for
+# LinearSegmentedColormaps. The advantage of keeping
+# datad is that it delays the generation of the Colormap
+# instance until it is actually needed. Generating the
+# instance is fast enough, and typically done few enough
+# times, that there is no need to cache the result.
 
+def register_cmap(name=None, cmap=None, data=None, lut=None):
+ """
+ Add a colormap to the set recognized by :func:`get_cmap`.
+
+ It can be used in two ways::
+
+ register_cmap(name='swirly', cmap=swirly_cmap)
+
+ register_cmap(name='choppy', data=choppydata, lut=128)
+
+ In the first case, *cmap* must be a :class:`colors.Colormap`
+ instance. The *name* is optional; if absent, the name will
+ be the :attr:`name` attribute of the *cmap*.
+
+ In the second case, the three arguments are passed to
+ the :class:`colors.LinearSegmentedColormap` initializer,
+ and the resulting colormap is registered.
+
+ """
+ if name is None:
+ try:
+ name = cmap.name
+ except AttributeError:
+ raise ValueError("Arguments must include a name or a Colormap")
+
+ if not cbook.is_string_like(name):
+ raise ValueError("Colormap name must be a string")
+
+ if isinstance(cmap, colors.Colormap):
+ cmap_d[name] = cmap
+ return
+
+ # For the remainder, let exceptions propagate.
+ if lut is None:
+ lut = mpl.rcParams['image.lut']
+ cmap = colors.LinearSegmentedColormap(name, data, lut)
+ cmap_d[name] = cmap
+
 def get_cmap(name=None, lut=None):
 """
- Get a colormap instance, defaulting to rc values if *name* is None
+ Get a colormap instance, defaulting to rc values if *name* is None.
+
+ Colormaps added with :func:`register_cmap` take precedence over
+ builtin colormaps.
+
+ If *name* is a :class:`colors.Colormap` instance, it will be
+ returned.
 """
- if name is None: name = mpl.rcParams['image.cmap']
- if lut is None: lut = mpl.rcParams['image.lut']
+ if name is None:
+ name = mpl.rcParams['image.cmap']
 
- assert(name in datad.keys())
+ if isinstance(name, colors.Colormap):
+ return name
+
+ if name in cmap_d:
+ return cmap_d[name]
+
+ if name not in datad:
+ raise ValueError("%s is not a known colormap name" % name)
+
+ if lut is None:
+ lut = mpl.rcParams['image.lut']
 return colors.LinearSegmentedColormap(name, datad[name], lut)
 
 class ScalarMappable:
@@ -116,9 +179,9 @@
 """
 set the colormap for luminance data
 
- ACCEPTS: a colormap
+ ACCEPTS: a colormap or registered colormap name
 """
- if cmap is None: cmap = get_cmap()
+ cmap = get_cmap(cmap)
 self.cmap = cmap
 self.changed()
 
Modified: trunk/matplotlib/lib/matplotlib/image.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/image.py	2009年07月30日 17:08:23 UTC (rev 7308)
+++ trunk/matplotlib/lib/matplotlib/image.py	2009年07月30日 19:32:15 UTC (rev 7309)
@@ -512,7 +512,7 @@
 def set_cmap(self, cmap):
 if self._A is not None:
 raise RuntimeError('Cannot change colors after loading data')
- cm.ScalarMappable.set_cmap(self, norm)
+ cm.ScalarMappable.set_cmap(self, cmap)
 
 class PcolorImage(martist.Artist, cm.ScalarMappable):
 '''
Modified: trunk/matplotlib/lib/matplotlib/pyplot.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/pyplot.py	2009年07月30日 17:08:23 UTC (rev 7308)
+++ trunk/matplotlib/lib/matplotlib/pyplot.py	2009年07月30日 19:32:15 UTC (rev 7309)
@@ -17,7 +17,7 @@
 from matplotlib.scale import get_scale_docs, get_scale_names
 
 from matplotlib import cm
-from matplotlib.cm import get_cmap
+from matplotlib.cm import get_cmap, register_cmap
 
 import numpy as np
 
@@ -1396,8 +1396,26 @@
 im.set_clim(vmin, vmax)
 draw_if_interactive()
 
+def set_cmap(cmap):
+ '''
+ set the default colormap to *cmap* and apply to current image if any.
+ See help(colormaps) for more information.
 
+ *cmap* must be a :class:`colors.Colormap` instance, or
+ the name of a registered colormap.
 
+ See :func:`register_cmap` and :func:`get_cmap`.
+ '''
+ cmap = cm.get_cmap(cmap)
+
+ rc('image', cmap=cmap.name)
+ im = gci()
+
+ if im is not None:
+ im.set_cmap(cmap)
+ draw_if_interactive()
+
+
 def imread(*args, **kwargs):
 return _imread(*args, **kwargs)
 if _imread.__doc__ is not None:
@@ -6327,12 +6345,12 @@
 *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.
 
@@ -6365,7 +6383,7 @@
 
 *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.
 
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 7308
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=7308&view=rev
Author: leejjoon
Date: 2009年07月30日 17:08:23 +0000 (2009年7月30日)
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.