matplotlib-checkins Mailing List for matplotlib

Revision: 5551
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5551&view=rev
Author: dsdale
Date: 2008年06月15日 16:53:06 -0700 (2008年6月15日)
Log Message:
-----------
added cm and collections to api reference
Modified Paths:
--------------
 trunk/matplotlib/doc/api/index.rst
 trunk/matplotlib/lib/matplotlib/cm.py
 trunk/matplotlib/lib/matplotlib/collections.py
Modified: trunk/matplotlib/doc/api/index.rst
===================================================================
--- trunk/matplotlib/doc/api/index.rst	2008年06月15日 23:05:34 UTC (rev 5550)
+++ trunk/matplotlib/doc/api/index.rst	2008年06月15日 23:53:06 UTC (rev 5551)
@@ -16,5 +16,7 @@
 axes_api.rst
 axis_api.rst
 cbook_api.rst
+ cm_api.rst
+ collections_api.rst
 pyplot_api.rst
 index_backend_api.rst
Modified: trunk/matplotlib/lib/matplotlib/cm.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/cm.py	2008年06月15日 23:05:34 UTC (rev 5550)
+++ trunk/matplotlib/lib/matplotlib/cm.py	2008年06月15日 23:53:06 UTC (rev 5551)
@@ -13,7 +13,7 @@
 
 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
 """
 if name is None: name = mpl.rcParams['image.cmap']
 if lut is None: lut = mpl.rcParams['image.lut']
@@ -29,8 +29,9 @@
 
 def __init__(self, norm=None, cmap=None):
 """
- norm is a colors.normalize instance to map luminance to 0-1
- cmap is a cm colormap instance
+ *norm* is an instance of :class:`colors.Normalize` or one of
+ its subclasses, used to map luminance to 0-1. *cmap* is a
+ :mod:`cm` colormap instance, for example :data:`cm.jet`
 """
 
 self.callbacksSM = cbook.CallbackRegistry((
@@ -50,10 +51,10 @@
 self.colorbar = im, ax
 
 def to_rgba(self, x, alpha=1.0, bytes=False):
- '''Return a normalized rgba array corresponding to x.
- If x is already an rgb array, insert alpha; if it is
- already rgba, return it unchanged.
- If bytes is True, return rgba as 4 uint8s instead of 4 floats.
+ '''Return a normalized rgba array corresponding to *x*. If *x*
+ is already an rgb array, insert *alpha*; if it is already
+ rgba, return it unchanged. If *bytes* is True, return rgba as
+ 4 uint8s instead of 4 floats.
 '''
 try:
 if x.ndim == 3:
@@ -79,7 +80,7 @@
 return x
 
 def set_array(self, A):
- 'Set the image array from numpy array A'
+ 'Set the image array from numpy array *A*'
 self._A = A
 self.update_dict['array'] = True
 
@@ -97,8 +98,8 @@
 
 def set_clim(self, vmin=None, vmax=None):
 """
- set the norm limits for image scaling; if vmin is a length2
- sequence, interpret it as (vmin, vmax) which is used to
+ set the norm limits for image scaling; if *vmin* is a length2
+ sequence, interpret it as ``(vmin, vmax)`` which is used to
 support setp
 
 ACCEPTS: a length 2 sequence of floats
Modified: trunk/matplotlib/lib/matplotlib/collections.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/collections.py	2008年06月15日 23:05:34 UTC (rev 5550)
+++ trunk/matplotlib/lib/matplotlib/collections.py	2008年06月15日 23:53:06 UTC (rev 5551)
@@ -1,10 +1,11 @@
 """
 Classes for the efficient drawing of large collections of objects that
-share most properties, eg a large number of line segments or polygons
+share most properties, e.g. a large number of line segments or
+polygons.
 
 The classes are not meant to be as flexible as their single element
-counterparts (eg you may not be able to select all line styles) but
-they are meant to be fast for common use cases (eg a bunch of solid
+counterparts (e.g. you may not be able to select all line styles) but
+they are meant to be fast for common use cases (e.g. a bunch of solid
 line segemnts)
 """
 import math, warnings
@@ -24,32 +25,34 @@
 
 All properties in a collection must be sequences or scalars;
 if scalars, they will be converted to sequences. The
- property of the ith element of the collection is the
+ property of the ith element of the collection is::
 
- prop[i % len(props)].
+ prop[i % len(props)]
 
- kwargs are:
+ Keyword arguments and default values:
 
- edgecolors=None,
- facecolors=None,
- linewidths=None,
- antialiaseds = None,
- offsets = None,
- transOffset = transforms.IdentityTransform(),
- norm = None, # optional for cm.ScalarMappable
- cmap = None, # ditto
+ * *edgecolors*: None
+ * *facecolors*: None
+ * *linewidths*: None
+ * *antialiaseds*: None
+ * *offsets*: None
+ * *transOffset*: transforms.IdentityTransform()
+ * *norm*: None (optional for
+ :class:`matplotlib.cm.ScalarMappable`)
+ * *cmap*: None (optional for
+ :class:`matplotlib.cm.ScalarMappable`)
 
- offsets and transOffset are used to translate the patch after
- rendering (default no offsets)
+ *offsets* and *transOffset* are used to translate the patch after
+ rendering (default no offsets).
 
- If any of edgecolors, facecolors, linewidths, antialiaseds are
- None, they default to their patch.* rc params setting, in sequence
- form.
+ If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*
+ are None, they default to their :data:`matplotlib.rcParams` patch
+ setting, in sequence form.
 
- The use of ScalarMappable is optional. If the ScalarMappable
- matrix _A is not None (ie a call to set_array has been made), at
- draw time a call to scalar mappable will be made to set the face
- colors.
+ The use of :class:`~matplotlib.cm.ScalarMappable` is optional. If
+ the :class:`~matplotlib.cm.ScalarMappable` matrix _A is not None
+ (ie a call to set_array has been made), at draw time a call to
+ scalar mappable will be made to set the face colors.
 """
 _offsets = np.array([], np.float_)
 _transOffset = transforms.IdentityTransform()
@@ -193,7 +196,8 @@
 """
 Test whether the mouse event occurred in the collection.
 
- Returns T/F, dict(ind=itemlist), where every item in itemlist contains the event.
+ Returns True | False, ``dict(ind=itemlist)``, where every
+ item in itemlist contains the event.
 """
 if callable(self._contains): return self._contains(self,mouseevent)
 
@@ -215,9 +219,9 @@
 
 def set_linewidths(self, lw):
 """
- Set the linewidth(s) for the collection. lw can be a scalar or a
- sequence; if it is a sequence the patches will cycle through the
- sequence
+ Set the linewidth(s) for the collection. *lw* can be a scalar
+ or a sequence; if it is a sequence the patches will cycle
+ through the sequence
 
 ACCEPTS: float or sequence of floats
 """
@@ -228,7 +232,7 @@
 def set_linestyles(self, ls):
 """
 Set the linestyles(s) for the collection.
- ACCEPTS: ['solid' | 'dashed', 'dashdot', 'dotted' | (offset, on-off-dash-seq) ]
+ ACCEPTS: ['solid' | 'dashed', 'dashdot', 'dotted' | (offset, on-off-dash-seq) ]
 """
 try:
 dashd = backend_bases.GraphicsContextBase.dashd
@@ -280,7 +284,7 @@
 def set_color(self, c):
 """
 Set both the edgecolor and the facecolor.
- See set_facecolor and set_edgecolor.
+ See :meth:`set_facecolor` and :meth:`set_edgecolor`.
 
 ACCEPTS: matplotlib color arg or sequence of rgba tuples
 """
@@ -289,10 +293,10 @@
 
 def set_facecolor(self, c):
 """
- Set the facecolor(s) of the collection. c can be a matplotlib
- color arg (all patches have same color), or a a sequence or
- rgba tuples; if it is a sequence the patches will cycle
- through the sequence
+ Set the facecolor(s) of the collection. *c* can be a
+ matplotlib color arg (all patches have same color), or a
+ sequence or rgba tuples; if it is a sequence the patches will
+ cycle through the sequence
 
 ACCEPTS: matplotlib color arg or sequence of rgba tuples
 """
@@ -307,9 +311,10 @@
 
 def set_edgecolor(self, c):
 """
- Set the edgecolor(s) of the collection. c can be a matplotlib color
- arg (all patches have same color), or a a sequence or rgba tuples; if
- it is a sequence the patches will cycle through the sequence
+ Set the edgecolor(s) of the collection. *c* can be a
+ matplotlib color arg (all patches have same color), or a
+ sequence or rgba tuples; if it is a sequence the patches will
+ cycle through the sequence
 
 ACCEPTS: matplotlib color arg or sequence of rgba tuples
 """
@@ -320,7 +325,7 @@
 
 def set_alpha(self, alpha):
 """
- Set the alpha tranparencies of the collection. Alpha must be
+ Set the alpha tranparencies of the collection. *alpha* must be
 a float.
 
 ACCEPTS: float
@@ -364,23 +369,25 @@
 # class is built so we define an initial set here for the init
 # function and they will be overridden after object defn
 artist.kwdocd['Collection'] = """\
- Valid Collection kwargs are:
+ Valid Collection keyword arguments:
 
- edgecolors=None,
- facecolors=None,
- linewidths=None,
- antialiaseds = None,
- offsets = None,
- transOffset = transforms.IdentityTransform(),
- norm = None, # optional for cm.ScalarMappable
- cmap = None, # ditto
+ * *edgecolors*: None
+ * *facecolors*: None
+ * *linewidths*: None
+ * *antialiaseds*: None
+ * *offsets*: None
+ * *transOffset*: transforms.IdentityTransform()
+ * *norm*: None (optional for
+ :class:`matplotlib.cm.ScalarMappable`)
+ * *cmap*: None (optional for
+ :class:`matplotlib.cm.ScalarMappable`)
 
- offsets and transOffset are used to translate the patch after
+ *offsets* and *transOffset* are used to translate the patch after
 rendering (default no offsets)
 
- If any of edgecolors, facecolors, linewidths, antialiaseds are
- None, they default to their patch.* rc params setting, in sequence
- form.
+ If any of *edgecolors*, *facecolors*, *linewidths*, *antialiaseds*
+ are None, they default to their :data:`matplotlib.rcParams` patch
+ setting, in sequence form.
 """
 
 class QuadMesh(Collection):
@@ -494,11 +501,11 @@
 class PolyCollection(Collection):
 def __init__(self, verts, sizes = None, **kwargs):
 """
- verts is a sequence of ( verts0, verts1, ...) where verts_i is
- a sequence of xy tuples of vertices, or an equivalent
- numpy array of shape (nv,2).
+ *verts* is a sequence of ( *verts0*, *verts1*, ...) where
+ *verts_i* is a sequence of xy tuples of vertices, or an
+ equivalent :mod:`numpy` array of shape (nv,2).
 
- sizes gives the area of the circle circumscribing the
+ *sizes* gives the area of the circle circumscribing the
 polygon in points^2
 
 %(Collection)s
@@ -532,9 +539,12 @@
 """
 def __init__(self, xranges, yrange, **kwargs):
 """
- xranges : sequence of (xmin, xwidth)
- yrange : ymin, ywidth
+ *xranges*
+ sequence of (xmin, xwidth)
 
+ *yrange*
+ ymin, ywidth
+
 %(Collection)s
 """
 ymin, ywidth = yrange
@@ -554,34 +564,38 @@
 """
 Draw a regular polygon with numsides.
 
- * dpi is the figure dpi instance, and is required to do the
- area scaling.
+ *dpi*
+ the figure dpi instance, and is required to do the
+ area scaling.
 
- * numsides: the number of sides of the polygon
+ *numsides*
+ the number of sides of the polygon
 
- * sizes gives the area of the circle circumscribing the
- regular polygon in points^2
+ *sizes*
+ gives the area of the circle circumscribing the
+ regular polygon in points^2
 
- * rotation is the rotation of the polygon in radians
+ *rotation*
+ the rotation of the polygon in radians
 
 %(Collection)s
 
- Example: see examples/dynamic_collection.py for complete example
+ Example: see :file:`examples/dynamic_collection.py` for
+ complete example::
 
- offsets = np.random.rand(20,2)
- facecolors = [cm.jet(x) for x in np.random.rand(20)]
- black = (0,0,0,1)
+ offsets = np.random.rand(20,2)
+ facecolors = [cm.jet(x) for x in np.random.rand(20)]
+ black = (0,0,0,1)
 
- collection = RegularPolyCollection(
- numsides=5, # a pentagon
- rotation=0,
- sizes=(50,),
- facecolors = facecolors,
- edgecolors = (black,),
- linewidths = (1,),
- offsets = offsets,
- transOffset = ax.transData,
- )
+ collection = RegularPolyCollection(
+ numsides=5, # a pentagon
+ rotation=0, sizes=(50,),
+ facecolors = facecolors,
+ edgecolors = (black,),
+ linewidths = (1,),
+ offsets = offsets,
+ transOffset = ax.transData,
+ )
 """
 Collection.__init__(self,**kwargs)
 self._sizes = sizes
@@ -633,42 +647,57 @@
 **kwargs
 ):
 """
- segments is a sequence of ( line0, line1, line2), where
- linen = (x0, y0), (x1, y1), ... (xm, ym), or the
- equivalent numpy array with two columns.
- Each line can be a different length.
+ *segments*
+ a sequence of ( *line0*, *line1*, *line2*), where::
 
- colors must be a tuple of RGBA tuples (eg arbitrary color
- strings, etc, not allowed).
+ linen = (x0, y0), (x1, y1), ... (xm, ym)
 
- antialiaseds must be a sequence of ones or zeros
+ or the equivalent numpy array with two columns. Each line
+ can be a different length.
 
- linestyles is a string or dash tuple. Legal string values are
- solid|dashed|dashdot|dotted. The dash tuple is (offset, onoffseq)
- where onoffseq is an even length tuple of on and off ink in points.
+ *colors*
+ must be a tuple of RGBA tuples (eg arbitrary color
+ strings, etc, not allowed).
 
- If linewidths, colors_, or antialiaseds is None, they default to
- their rc params setting, in sequence form.
+ *antialiaseds*
+ must be a sequence of ones or zeros
 
- If offsets and transOffset are not None, then
- offsets are transformed by transOffset and applied after
+ *linestyles* [ 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
+ a string or dash tuple. The dash tuple is::
+
+ (offset, onoffseq),
+
+ where *onoffseq* is an even length tuple of on and off ink
+ in points.
+
+ If *linewidths*, *colors*, or *antialiaseds* is None, they
+ default to their rcParams setting, in sequence form.
+
+ If *offsets* and *transOffset* are not None, then
+ *offsets* are transformed by *transOffset* and applied after
 the segments have been transformed to display coordinates.
 
- If offsets is not None but transOffset is None, then the
- offsets are added to the segments before any transformation.
- In this case, a single offset can be specified as offsets=(xo,yo),
- and this value will be
- added cumulatively to each successive segment, so as
- to produce a set of successively offset curves.
+ If *offsets* is not None but *transOffset* is None, then the
+ *offsets* are added to the segments before any transformation.
+ In this case, a single offset can be specified as::
 
- norm = None, # optional for ScalarMappable
- cmap = None, # ditto
+ offsets=(xo,yo)
 
- pickradius is the tolerance for mouse clicks picking a line. The
- default is 5 pt.
+ and this value will be added cumulatively to each successive
+ segment, so as to produce a set of successively offset curves.
 
- The use of ScalarMappable is optional. If the ScalarMappable
- matrix _A is not None (ie a call to set_array has been made), at
+ *norm*
+ None (optional for :class:`matplotlib.cm.ScalarMappable`)
+ *cmap*
+ None (optional for :class:`matplotlib.cm.ScalarMappable`)
+
+ *pickradius* is the tolerance for mouse clicks picking a line.
+ The default is 5 pt.
+
+ The use of :class:`~matplotlib.cm.ScalarMappable` is optional.
+ If the :class:`~matplotlib.cm.ScalarMappable` matrix
+ :attr:`~matplotlib.cm.ScalarMappable._A` is not None (ie a call to
+ :meth:`~matplotlib.cm.ScalarMappable.set_array` has been made), at
 draw time a call to scalar mappable will be made to set the colors.
 """
 if colors is None: colors = mpl.rcParams['lines.color']
@@ -721,8 +750,8 @@
 
 def set_color(self, c):
 """
- Set the color(s) of the line collection. c can be a
- matplotlib color arg (all patches have same color), or a a
+ Set the color(s) of the line collection. *c* can be a
+ matplotlib color arg (all patches have same color), or a
 sequence or rgba tuples; if it is a sequence the patches will
 cycle through the sequence
 
@@ -732,8 +761,8 @@
 
 def color(self, c):
 """
- Set the color(s) of the line collection. c can be a
- matplotlib color arg (all patches have same color), or a a
+ Set the color(s) of the line collection. *c* can be a
+ matplotlib color arg (all patches have same color), or a
 sequence or rgba tuples; if it is a sequence the patches will
 cycle through the sequence
 
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 5550
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5550&view=rev
Author: dsdale
Date: 2008年06月15日 16:05:34 -0700 (2008年6月15日)
Log Message:
-----------
add axis and cbook to api reference
Modified Paths:
--------------
 trunk/matplotlib/doc/api/index.rst
 trunk/matplotlib/lib/matplotlib/axis.py
 trunk/matplotlib/lib/matplotlib/cbook.py
Modified: trunk/matplotlib/doc/api/index.rst
===================================================================
--- trunk/matplotlib/doc/api/index.rst	2008年06月15日 20:38:00 UTC (rev 5549)
+++ trunk/matplotlib/doc/api/index.rst	2008年06月15日 23:05:34 UTC (rev 5550)
@@ -14,5 +14,7 @@
 matplotlib_configuration_api.rst
 artist_api.rst
 axes_api.rst
+ axis_api.rst
+ cbook_api.rst
 pyplot_api.rst
 index_backend_api.rst
Modified: trunk/matplotlib/lib/matplotlib/axis.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/axis.py	2008年06月15日 20:38:00 UTC (rev 5549)
+++ trunk/matplotlib/lib/matplotlib/axis.py	2008年06月15日 23:05:34 UTC (rev 5550)
@@ -23,19 +23,38 @@
 1 refers to the bottom of the plot for xticks and the left for yticks
 2 refers to the top of the plot for xticks and the right for yticks
 
- Publicly accessible attributes
+ Publicly accessible attributes:
 
- tick1line : a Line2D instance
- tick2line : a Line2D instance
- gridline : a Line2D instance
- label1 : a Text instance
- label2 : a Text instance
- gridOn : a boolean which determines whether to draw the tickline
- tick1On : a boolean which determines whether to draw the 1st tickline
- tick2On : a boolean which determines whether to draw the 2nd tickline
- label1On : a boolean which determines whether to draw tick label
- label2On : a boolean which determines whether to draw tick label
+ :attr:`tick1line`
+ a Line2D instance
 
+ :attr:`tick2line`
+ a Line2D instance
+
+ :attr:`gridline`
+ a Line2D instance
+
+ :attr:`label1`
+ a Text instance
+
+ :attr:`label2`
+ a Text instance
+
+ :attr:`gridOn`
+ a boolean which determines whether to draw the tickline
+
+ :attr:`tick1On`
+ a boolean which determines whether to draw the 1st tickline
+
+ :attr:`tick2On`
+ a boolean which determines whether to draw the 2nd tickline
+
+ :attr:`label1On`
+ a boolean which determines whether to draw tick label
+
+ :attr:`label2On`
+ a boolean which determines whether to draw tick label
+
 """
 def __init__(self, axes, loc, label,
 size = None, # points
@@ -111,7 +130,8 @@
 return self.figure.dpi * self._pad / 72.0
 
 def contains(self, mouseevent):
- """Test whether the mouse event occured in the Tick marks.
+ """
+ Test whether the mouse event occured in the Tick marks.
 
 This function always returns false. It is more useful to test if the
 axis as a whole contains the mouse rather than the set of tick marks.
Modified: trunk/matplotlib/lib/matplotlib/cbook.py
===================================================================
--- trunk/matplotlib/lib/matplotlib/cbook.py	2008年06月15日 20:38:00 UTC (rev 5549)
+++ trunk/matplotlib/lib/matplotlib/cbook.py	2008年06月15日 23:05:34 UTC (rev 5550)
@@ -40,7 +40,7 @@
 class todatetime(converter):
 'convert to a datetime or None'
 def __init__(self, fmt='%Y-%m-%d', missing='Null', missingval=None):
- 'use a time.strptime format string for conversion'
+ 'use a :func:`time.strptime` format string for conversion'
 converter.__init__(self, missing, missingval)
 self.fmt = fmt
 
@@ -54,7 +54,7 @@
 class todate(converter):
 'convert to a date or None'
 def __init__(self, fmt='%Y-%m-%d', missing='Null', missingval=None):
- 'use a time.strptime format string for conversion'
+ 'use a :func:`time.strptime` format string for conversion'
 converter.__init__(self, missing, missingval)
 self.fmt = fmt
 def __call__(self, s):
@@ -84,7 +84,7 @@
 class CallbackRegistry:
 """
 Handle registering and disconnecting for a set of signals and
- callbacks
+ callbacks::
 
 signals = 'eat', 'drink', 'be merry'
 
@@ -109,7 +109,7 @@
 
 """
 def __init__(self, signals):
- 'signals is a sequence of valid signals'
+ '*signals* is a sequence of valid signals'
 self.signals = set(signals)
 # callbacks is a dict mapping the signal to a dictionary
 # mapping callback id to the callback function
@@ -117,7 +117,7 @@
 self._cid = 0
 
 def _check_signal(self, s):
- 'make sure s is a valid signal or raise a ValueError'
+ 'make sure *s* is a valid signal or raise a ValueError'
 if s not in self.signals:
 signals = list(self.signals)
 signals.sort()
@@ -125,7 +125,7 @@
 
 def connect(self, s, func):
 """
- register func to be called when a signal s is generated
+ register *func* to be called when a signal *s* is generated
 func will be called
 """
 self._check_signal(s)
@@ -135,7 +135,7 @@
 
 def disconnect(self, cid):
 """
- disconnect the callback registered with callback id cid
+ disconnect the callback registered with callback id *cid*
 """
 for eventname, callbackd in self.callbacks.items():
 try: del callbackd[cid]
@@ -144,8 +144,8 @@
 
 def process(self, s, *args, **kwargs):
 """
- process signal s. All of the functions registered to receive
- callbacks on s will be called with *args and **kwargs
+ process signal *s*. All of the functions registered to receive
+ callbacks on *s* will be called with *\*args* and *\*\*kwargs*
 """
 self._check_signal(s)
 for func in self.callbacks[s].values():
@@ -194,42 +194,42 @@
 
 
 def unique(x):
- 'Return a list of unique elements of x'
+ 'Return a list of unique elements of *x*'
 return dict([ (val, 1) for val in x]).keys()
 
 def iterable(obj):
- 'return true if obj is iterable'
+ 'return true if *obj* is iterable'
 try: len(obj)
 except: return 0
 return 1
 
 
 def is_string_like(obj):
- 'return true if obj looks like a string'
+ 'return true if *obj* looks like a string'
 if hasattr(obj, 'shape'): return 0
 try: obj + ''
 except (TypeError, ValueError): return 0
 return 1
 
 def is_writable_file_like(obj):
- 'return true if obj looks like a file object'
+ 'return true if *obj* looks like a file object'
 return hasattr(obj, 'write') and callable(obj.write)
 
 def is_scalar(obj):
- 'return true if ob is not string like and is not iterable'
+ 'return true if *obj* is not string like and is not iterable'
 return is_string_like(obj) or not iterable(obj)
 
 def is_numlike(obj):
- 'return true if obj looks like a number'
+ 'return true if *obj* looks like a number'
 try: obj+1
 except TypeError: return False
 else: return True
 
 def to_filehandle(fname, flag='r', return_opened=False):
 """
- fname can be a filename or a file handle. Support for gzipped
- files is automatic, if the filename ends in .gz. flag is a
- read/write flag for file
+ *fname* can be a filename or a file handle. Support for gzipped
+ files is automatic, if the filename ends in .gz. *flag* is a
+ read/write flag for :func:`file`
 """
 if is_string_like(fname):
 if fname.endswith('.gz'):
@@ -275,18 +275,19 @@
 
 Sort by attribute or item
 
- Example usage:
- sort = Sorter()
+ Example usage::
 
- list = [(1, 2), (4, 8), (0, 3)]
- dict = [{'a': 3, 'b': 4}, {'a': 5, 'b': 2}, {'a': 0, 'b': 0},
- {'a': 9, 'b': 9}]
+ sort = Sorter()
 
+ list = [(1, 2), (4, 8), (0, 3)]
+ dict = [{'a': 3, 'b': 4}, {'a': 5, 'b': 2}, {'a': 0, 'b': 0},
+ {'a': 9, 'b': 9}]
 
- sort(list) # default sort
- sort(list, 1) # sort by index 1
- sort(dict, 'a') # sort a list of dicts by key 'a'
 
+ sort(list) # default sort
+ sort(list, 1) # sort by index 1
+ sort(dict, 'a') # sort a list of dicts by key 'a'
+
 """
 
 def _helper(self, data, aux, inplace):
@@ -324,19 +325,19 @@
 """
 All-in-one multiple-string-substitution class
 
- Example usage:
+ Example usage::
 
- text = "Larry Wall is the creator of Perl"
- adict = {
- "Larry Wall" : "Guido van Rossum",
- "creator" : "Benevolent Dictator for Life",
- "Perl" : "Python",
- }
+ text = "Larry Wall is the creator of Perl"
+ adict = {
+ "Larry Wall" : "Guido van Rossum",
+ "creator" : "Benevolent Dictator for Life",
+ "Perl" : "Python",
+ }
 
- print multiple_replace(adict, text)
+ print multiple_replace(adict, text)
 
- xlat = Xlator(adict)
- print xlat.xlat(text)
+ xlat = Xlator(adict)
+ print xlat.xlat(text)
 """
 
 def _make_regex(self):
@@ -344,11 +345,11 @@
 return re.compile("|".join(map(re.escape, self.keys())))
 
 def __call__(self, match):
- """ Handler invoked for each regex match """
+ """ Handler invoked for each regex *match* """
 return self[match.group(0)]
 
 def xlat(self, text):
- """ Translate text, returns the modified text. """
+ """ Translate *text*, returns the modified text. """
 return self._make_regex().sub(self, text)
 
 
@@ -424,7 +425,7 @@
 get_realpath_and_stat = GetRealpathAndStat()
 
 def dict_delall(d, keys):
- 'delete all of the keys from the dict d'
+ 'delete all of the *keys* from the :class:`dict` *d*'
 for key in keys:
 try: del d[key]
 except KeyError: pass
@@ -464,10 +465,13 @@
 
 
 def get_split_ind(seq, N):
- """seq is a list of words. Return the index into seq such that
- len(' '.join(seq[:ind])<=N
 """
+ *seq* is a list of words. Return the index into seq such that::
 
+ len(' '.join(seq[:ind])<=N
+
+ """
+
 sLen = 0
 # todo: use Alex's xrange pattern from the cbook for efficiency
 for (word, ind) in zip(seq, range(len(seq))):
@@ -477,7 +481,7 @@
 
 
 def wrap(prefix, text, cols):
- 'wrap text with prefix at length cols'
+ 'wrap *text* with *prefix* at length *cols*'
 pad = ' '*len(prefix.expandtabs())
 available = cols - len(pad)
 
@@ -504,14 +508,13 @@
 _dedent_regex = {}
 def dedent(s):
 """
- Remove excess indentation from docstrings.
+ Remove excess indentation from docstring *s*.
 
- Discards any leading blank lines, then removes up to
- n whitespace characters from each line, where n is
- the number of leading whitespace characters in the
- first line. It differs from textwrap.dedent in its
- deletion of leading blank lines and its use of the
- first non-blank line to determine the indentation.
+ Discards any leading blank lines, then removes up to n whitespace
+ characters from each line, where n is the number of leading
+ whitespace characters in the first line. It differs from
+ textwrap.dedent in its deletion of leading blank lines and its use
+ of the first non-blank line to determine the indentation.
 
 It is also faster in most cases.
 """
@@ -546,6 +549,7 @@
 def listFiles(root, patterns='*', recurse=1, return_folders=0):
 """
 Recursively list files
+
 from Parmar and Martelli in the Python Cookbook
 """
 import os.path, fnmatch
@@ -575,8 +579,8 @@
 
 def get_recursive_filelist(args):
 """
- Recurs all the files and dirs in args ignoring symbolic links and
- return the files as a list of strings
+ Recurs all the files and dirs in *args* ignoring symbolic links
+ and return the files as a list of strings
 """
 files = []
 
@@ -593,7 +597,7 @@
 
 
 def pieces(seq, num=2):
- "Break up the seq into num tuples"
+ "Break up the *seq* into *num* tuples"
 start = 0
 while 1:
 item = seq[start:start+num]
@@ -611,8 +615,8 @@
 
 def allequal(seq):
 """
- return true if all elements of seq compare equal. If seq is 0 or
- 1 length, return True
+ return true if all elements of *seq* compare equal. If *seq* is 0
+ or 1 length, return *True*
 """
 if len(seq)<2: return True
 val = seq[0]
@@ -637,10 +641,11 @@
 
 def allpairs(x):
 """
- return all possible pairs in sequence x
+ return all possible pairs in sequence *x*
 
- Condensed by Alex Martelli from this thread on c.l.python
- http://groups.google.com/groups?q=all+pairs+group:*python*&hl=en&lr=&ie=UTF-8&selm=mailman.4028.1096403649.5135.python-list%40python.org&rnum=1
+ Condensed by Alex Martelli from this thread_ on c.l.python
+
+ .. _thread: http://groups.google.com/groups?q=all+pairs+group:*python*&hl=en&lr=&ie=UTF-8&selm=mailman.4028.1096403649.5135.python-list%40python.org&rnum=1
 """
 return [ (s, f) for i, f in enumerate(x) for s in x[i+1:] ]
 
@@ -650,15 +655,17 @@
 # python 2.2 dicts don't have pop--but we don't support 2.2 any more
 def popd(d, *args):
 """
- Should behave like python2.3 pop method; d is a dict
+ Should behave like python2.3 :meth:`dict.pop` method; *d* is a
+ :class:`dict`::
 
- # returns value for key and deletes item; raises a KeyError if key
- # is not in dict
- val = popd(d, key)
+ # returns value for key and deletes item; raises a KeyError if key
+ # is not in dict
+ val = popd(d, key)
 
- # returns value for key if key exists, else default. Delete key,
- # val item if it exists. Will not raise a KeyError
- val = popd(d, key, default)
+ # returns value for key if key exists, else default. Delete key,
+ # val item if it exists. Will not raise a KeyError
+ val = popd(d, key, default)
+
 """
 if len(args)==1:
 key = args[0]
@@ -744,8 +751,8 @@
 
 def bubble(self, o):
 """
- raise o to the top of the stack and return o. o must be in
- the stack
+ raise *o* to the top of the stack and return *o*. *o* must be
+ in the stack
 """
 
 if o not in self._elements:
@@ -761,7 +768,7 @@
 return o
 
 def remove(self, o):
- 'remove element o from the stack'
+ 'remove element *o* from the stack'
 if o not in self._elements:
 raise ValueError('Unknown element o')
 old = self._elements[:]
@@ -776,7 +783,7 @@
 
 def finddir(o, match, case=False):
 """
- return all attributes of o which match string in match. if case
+ return all attributes of *o* which match string in match. if case
 is True require an exact case match.
 """
 if case:
@@ -787,7 +794,7 @@
 return [orig for name, orig in names if name.find(match)>=0]
 
 def reverse_dict(d):
- 'reverse the dictionary -- may lose data if values are not uniq!'
+ 'reverse the dictionary -- may lose data if values are not unique!'
 return dict([(v,k) for k,v in d.items()])
 
 
@@ -808,7 +815,7 @@
 
 _safezip_msg = 'In safezip, len(args[0])=%d but len(args[%d])=%d'
 def safezip(*args):
- 'make sure args are equal len before zipping'
+ 'make sure *args* are equal len before zipping'
 Nx = len(args[0])
 for i, arg in enumerate(args[1:]):
 if len(arg) != Nx:
@@ -870,12 +877,16 @@
 
 def print_cycles(objects, outstream=sys.stdout, show_progress=False):
 """
- objects: A list of objects to find cycles in. It is often useful
- to pass in gc.garbage to find the cycles that are
- preventing some objects from being garbage collected.
- outstream: The stream for output.
- show_progress: If True, print the number of objects reached as they are
- found.
+ *objects*
+ A list of objects to find cycles in. It is often useful to
+ pass in gc.garbage to find the cycles that are preventing some
+ objects from being garbage collected.
+
+ *outstream*
+ The stream for output.
+
+ *show_progress*
+ If True, print the number of objects reached as they are found.
 """
 import gc
 from types import FrameType
@@ -936,9 +947,9 @@
 together into disjoint sets when a full-blown graph data structure
 would be overkill.
 
- Objects can be joined using .join(), tested for connectedness
- using .joined(), and all disjoint sets can be retreived using
- .get().
+ Objects can be joined using :meth:`join`, tested for connectedness
+ using :meth:`joined`, and all disjoint sets can be retreived using
+ :meth:`get`.
 
 The objects being joined must be hashable.
 
@@ -987,7 +998,7 @@
 
 def joined(self, a, b):
 """
- Returns True if a and b are members of the same set.
+ Returns True if *a* and *b* are members of the same set.
 """
 mapping = self._mapping
 try:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 5549
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5549&view=rev
Author: astraw
Date: 2008年06月15日 13:38:00 -0700 (2008年6月15日)
Log Message:
-----------
fix example to run with current MPL and numpy
Modified Paths:
--------------
 trunk/matplotlib/examples/units/date_converter.py
Modified: trunk/matplotlib/examples/units/date_converter.py
===================================================================
--- trunk/matplotlib/examples/units/date_converter.py	2008年06月15日 15:29:57 UTC (rev 5548)
+++ trunk/matplotlib/examples/units/date_converter.py	2008年06月15日 20:38:00 UTC (rev 5549)
@@ -1,7 +1,8 @@
 import date_support # set up the date converters
 import datetime
 from matplotlib.dates import drange
-from pylab import figure, show, nx
+from pylab import figure, show
+import numpy as np
 
 
 xmin = datetime.date(2007,1,1)
@@ -12,7 +13,7 @@
 fig = figure()
 fig.subplots_adjust(bottom=0.2)
 ax = fig.add_subplot(111)
-ax.plot(xdates, nx.mlab.rand(len(xdates)), 'o')
+ax.plot(xdates, np.random.rand(len(xdates)), 'o')
 ax.set_xlim(datetime.date(2007,2,1), datetime.date(2007,3,1))
 
 fig.autofmt_xdate()
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 5548
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5548&view=rev
Author: dsdale
Date: 2008年06月15日 08:29:57 -0700 (2008年6月15日)
Log Message:
-----------
Expanded on documentation guidelines
Modified Paths:
--------------
 trunk/matplotlib/doc/devel/documenting_mpl.rst
 trunk/matplotlib/doc/glossary/index.rst
Modified: trunk/matplotlib/doc/devel/documenting_mpl.rst
===================================================================
--- trunk/matplotlib/doc/devel/documenting_mpl.rst	2008年06月15日 12:08:13 UTC (rev 5547)
+++ trunk/matplotlib/doc/devel/documenting_mpl.rst	2008年06月15日 15:29:57 UTC (rev 5548)
@@ -33,6 +33,7 @@
 The output produced by Sphinx can be configured by editing the `conf.py`
 file located in the `doc/`.
 
+
 Organization of matplotlib's documentation
 ==========================================
 
@@ -50,6 +51,7 @@
 
 .. include:: ../../TODO
 
+ 
 Formatting
 ==========
 
@@ -61,6 +63,20 @@
 other semantic markup. For example, when referring to external files, use the
 ``:file:`` directive.
 
+* Function arguments and keywords should be referred to using the *emphasis*
+ role. This will keep matplotlib's documentation consistant with Python's
+ documentation::
+
+ Here is a description of *argument*
+
+ Please do not use the `default role`::
+
+ Please do not describe `argument` like this.
+
+ nor the ``literal`` role::
+
+ Please do not describe ``argument`` like this.
+ 
 * Sphinx does not support tables with column- or row-spanning cells for
 latex output. Such tables can not be used when documenting matplotlib.
 
@@ -92,10 +108,96 @@
 
 In [69]: lines = plot([1,2,3])
 
+* Footnotes [#]_ can be added using ``[#]_``, followed later by::
+
+ .. rubric:: Footnotes
+
+ .. [#]
+
+ .. rubric:: Footnotes
+
+ .. [#] For example.
+
+* Use the *note* and *warning* directives, sparingly, to draw attention to
+ important comments::
+
+ .. note::
+ Here is a note
+
+ yields:
+
+ .. note::
+ here is a note
+
+ also:
+
+ .. warning::
+ here is a warning
+
+* Use the *deprecated* directive when appropriate::
+
+ .. deprecated:: 0.98
+ This feature is obsolete, use something else.
+
+ yields:
+
+ .. deprecated:: 0.98
+ This feature is obsolete, use something else.
+
+* Use the *versionadded* and *versionchanged* directives, which have similar
+ syntax to the *deprecated* role::
+
+ .. versionadded:: 0.98
+ The transforms have been completely revamped.
+
+ .. versionadded:: 0.98
+ The transforms have been completely revamped.
+ 
+* Use the *seealso* directive, for example::
+
+ .. seealso::
+
+ Using ReST :ref:`emacs-helpers`:
+ One example
+
+ A bit about :ref:`referring-to-mpl-docs`:
+ One more
+
+ yields:
+ 
+ .. seealso::
+
+ Using ResT :ref:`emacs-helpers`:
+ One example
+
+ A bit about :ref:`referring-to-mpl-docs`:
+ One more
+
+* Please keep the :ref:`glossary` in mind when writing documentation. You can
+ create a references to a term in the glossary with the ``:term:`` role.
+
+* The autodoc extension will handle index entries for the API, but additional
+ entries in the index_ need to be explicitly added.
+ 
 .. _documentation: http://sphinx.pocoo.org/contents.html
 .. _`inline markup`: http://sphinx.pocoo.org/markup/inline.html
+.. _index: http://sphinx.pocoo.org/markup/para.html#index-generating-markup
 
+Docstrings
+----------
 
+In addition to the aforementioned formatting suggestions:
+
+* Please limit the text width of docstrings to 70 characters.
+ 
+* Keyword arguments should be described using a definition list.
+
+ .. note::
+ matplotlib makes extensive use of keyword arguments as pass-through
+ arguments, there are a many cases where a table is used in place of a
+ definition list for autogenerated sections of docstrings.
+ 
+
 Figures
 =======
 
@@ -139,7 +241,6 @@
 :include-source
 
 
-
 .. _referring-to-mpl-docs:
 
 Referring to mpl documents
@@ -166,8 +267,6 @@
 .. literalinclude:: ../mpl_data/matplotlibrc
 
 
-
-
 .. _internal-section-refs:
 
 Internal section references
@@ -196,8 +295,8 @@
 In addition, since underscores are widely used by Sphinx itself, let's prefer
 hyphens to separate words.
 
-.. _emacs-helpers:
 
+
 Section names, etc
 ==================
 
@@ -205,6 +304,9 @@
 section titles, eg ``Possible hangups`` rather than ``Possible
 Hangups``
 
+
+.. _emacs-helpers:
+
 Emacs helpers
 =============
 
Modified: trunk/matplotlib/doc/glossary/index.rst
===================================================================
--- trunk/matplotlib/doc/glossary/index.rst	2008年06月15日 12:08:13 UTC (rev 5547)
+++ trunk/matplotlib/doc/glossary/index.rst	2008年06月15日 15:29:57 UTC (rev 5548)
@@ -1,6 +1,9 @@
-########
+
+.. _glossary:
+
+********
 Glossary
-########
+********
 
 .. glossary::
 
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

Revision: 5547
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5547&view=rev
Author: jswhit
Date: 2008年06月15日 05:08:13 -0700 (2008年6月15日)
Log Message:
-----------
moved to __init__.py so Sphinx can find docstrings.
Removed Paths:
-------------
 trunk/toolkits/basemap/lib/mpl_toolkits/basemap/basemap.py
Deleted: trunk/toolkits/basemap/lib/mpl_toolkits/basemap/basemap.py
===================================================================
--- trunk/toolkits/basemap/lib/mpl_toolkits/basemap/basemap.py	2008年06月15日 11:57:51 UTC (rev 5546)
+++ trunk/toolkits/basemap/lib/mpl_toolkits/basemap/basemap.py	2008年06月15日 12:08:13 UTC (rev 5547)
@@ -1,3344 +0,0 @@
-"""
-Module for plotting data on maps with matplotlib.
-
-Contains the Basemap class (which does most of the 
-heavy lifting), and the following functions:
-
-NetCDFFile: Read local and remote NetCDF datasets.
-
-interp: bilinear interpolation between rectilinear grids.
-
-shiftgrid: shifts global lat/lon grids east or west.
-
-addcyclic: Add cyclic (wraparound) point in longitude.
-
-num2date: convert from a numeric time value to a datetime object.
-
-date2num: convert from a datetime object to a numeric time value.
-"""
-from matplotlib import __version__ as _matplotlib_version
-from matplotlib.cbook import is_scalar, dedent
-# check to make sure matplotlib is not too old.
-_mpl_required_version = '0.98'
-if _matplotlib_version < _mpl_required_version:
- msg = dedent("""
- your matplotlib is too old - basemap requires version %s or 
- higher, you have version %s""" % 
- (_mpl_required_version,_matplotlib_version))
- raise ImportError(msg)
-from matplotlib import rcParams, is_interactive, _pylab_helpers
-from matplotlib.collections import LineCollection
-from matplotlib.patches import Ellipse, Circle, Polygon
-from matplotlib.lines import Line2D
-from matplotlib.transforms import Bbox
-import pyproj, sys, os, math, dbflib
-from proj import Proj
-import numpy as np
-import numpy.ma as ma
-from shapelib import ShapeFile
-import _geoslib, pupynere, netcdftime
-
-# basemap data files now installed in lib/matplotlib/toolkits/basemap/data
-basemap_datadir = os.sep.join([os.path.dirname(__file__), 'data'])
-
-__version__ = '0.99'
-
-# supported map projections.
-_projnames = {'cyl' : 'Cylindrical Equidistant',
- 'merc' : 'Mercator',
- 'tmerc' : 'Transverse Mercator',
- 'omerc' : 'Oblique Mercator',
- 'mill' : 'Miller Cylindrical',
- 'lcc' : 'Lambert Conformal',
- 'laea' : 'Lambert Azimuthal Equal Area',
- 'nplaea' : 'North-Polar Lambert Azimuthal',
- 'splaea' : 'South-Polar Lambert Azimuthal',
- 'eqdc' : 'Equidistant Conic',
- 'aeqd' : 'Azimuthal Equidistant',
- 'npaeqd' : 'North-Polar Azimuthal Equidistant',
- 'spaeqd' : 'South-Polar Azimuthal Equidistant',
- 'aea' : 'Albers Equal Area',
- 'stere' : 'Stereographic',
- 'npstere' : 'North-Polar Stereographic',
- 'spstere' : 'South-Polar Stereographic',
- 'cass' : 'Cassini-Soldner',
- 'poly' : 'Polyconic',
- 'ortho' : 'Orthographic',
- 'geos' : 'Geostationary',
- 'sinu' : 'Sinusoidal',
- 'moll' : 'Mollweide',
- 'robin' : 'Robinson',
- 'gnom' : 'Gnomonic',
- }
-supported_projections = []
-for _items in _projnames.iteritems():
- supported_projections.append("'%s' = %s\n" % (_items))
-supported_projections = ''.join(supported_projections)
-
-# projection specific parameters.
-projection_params = {'cyl' : 'corners only (no width/height)',
- 'merc' : 'corners plus lat_ts (no width/height)',
- 'tmerc' : 'lon_0,lat_0',
- 'omerc' : 'lon_0,lat_0,lat_1,lat_2,lon_1,lon_2,no_rot',
- 'mill' : 'corners only (no width/height)',
- 'lcc' : 'lon_0,lat_0,lat_1,lat_2',
- 'laea' : 'lon_0,lat_0',
- 'nplaea' : 'bounding_lat,lon_0,lat_0,no corners or width/height',
- 'splaea' : 'bounding_lat,lon_0,lat_0,no corners or width/height',
- 'eqdc' : 'lon_0,lat_0,lat_1,lat_2',
- 'aeqd' : 'lon_0,lat_0',
- 'npaeqd' : 'bounding_lat,lon_0,lat_0,no corners or width/height',
- 'spaeqd' : 'bounding_lat,lon_0,lat_0,no corners or width/height',
- 'aea' : 'lon_0,lat_0,lat_1',
- 'stere' : 'lon_0,lat_0,lat_ts',
- 'npstere' : 'bounding_lat,lon_0,lat_0,no corners or width/height',
- 'spstere' : 'bounding_lat,lon_0,lat_0,no corners or width/height',
- 'cass' : 'lon_0,lat_0',
- 'poly' : 'lon_0,lat_0',
- 'ortho' : 'lon_0,lat_0,llcrnrx,llcrnry,urcrnrx,urcrnry,no width/height',
- 'geos' : 'lon_0,satellite_height,llcrnrx,llcrnry,urcrnrx,urcrnry,no width/height',
- 'sinu' : 'lon_0,lat_0,no corners or width/height',
- 'moll' : 'lon_0,lat_0,no corners or width/height',
- 'robin' : 'lon_0,lat_0,no corners or width/height',
- 'gnom' : 'lon_0,lat_0',
- }
-
-# The __init__ docstring is pulled out here because it is so long;
-# Having it in the usual place makes it hard to get from the
-# __init__ argument list to the code that uses the arguments.
-_Basemap_init_doc = """
- create a Basemap instance.
-
- This sets up a basemap with specified map projection.
- and creates the coastline data structures in native map projection
- coordinates.
-
- arguments:
-
- projection - map projection. Supported projections are:
-%(supported_projections)s
- Default is 'cyl'.
-
- For most map projections, the map projection region can either be
- specified by setting these keywords:
-
- llcrnrlon - longitude of lower left hand corner of the desired map domain (degrees).
- llcrnrlat - latitude of lower left hand corner of the desired map domain (degrees).
- urcrnrlon - longitude of upper right hand corner of the desired map domain (degrees).
- urcrnrlat - latitude of upper right hand corner of the desired map domain (degrees).
-
- or these keywords:
-
- width - width of desired map domain in projection coordinates (meters).
- height - height of desired map domain in projection coordinates (meters).
- lon_0 - center of desired map domain (in degrees).
- lat_0 - center of desired map domain (in degrees).
-
- For 'sinu', 'moll', 'npstere', 'spstere', 'nplaea', 'splaea', 'nplaea',
- 'splaea', 'npaeqd', 'spaeqd' or 'robin', the values of
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat,width and height are ignored
- (because either they are computed internally, or entire globe is
- always plotted). For the cylindrical projections
- ('cyl','merc' and 'mill'), the default is to use
- llcrnrlon=-180,llcrnrlat=-90, urcrnrlon=180 and urcrnrlat=90). For all other
- projections except 'ortho' and 'geos', either the lat/lon values of the
- corners or width and height must be specified by the user.
- For 'ortho' and 'geos', the lat/lon values of the corners may be specified,
- or the x/y values of the corners (llcrnrx,llcrnry,urcrnrx,urcrnry) in the 
- coordinate system of the global projection (with x=0,y=0 at the center
- of the global projection). If the corners are not specified,
- the entire globe is plotted.
-
- resolution - resolution of boundary database to use. Can be 'c' (crude),
- 'l' (low), 'i' (intermediate), 'h' (high), 'f' (full) or None.
- If None, no boundary data will be read in (and class methods
- such as drawcoastlines will raise an exception if invoked).
- Resolution drops off by roughly 80%%
- between datasets. Higher res datasets are much slower to draw.
- Default 'c'. Coastline data is from the GSHHS
- (http://www.soest.hawaii.edu/wessel/gshhs/gshhs.html).
- State, country and river datasets from the Generic Mapping
- Tools (http://gmt.soest.hawaii.edu).
-
- area_thresh - coastline or lake with an area smaller than area_thresh
- in km^2 will not be plotted. Default 10000,1000,100,10,1 for resolution
- 'c','l','i','h','f'.
-
- rsphere - radius of the sphere used to define map projection (default
- 6370997 meters, close to the arithmetic mean radius of the earth). If
- given as a sequence, the first two elements are interpreted as
- the the radii of the major and minor axes of an ellipsoid. Note: sometimes
- an ellipsoid is specified by the major axis and an 'inverse flattening
- parameter' (if). The minor axis (b) can be computed from the major axis (a)
- and the inverse flattening parameter using the formula if = a/(a-b).
-
- suppress_ticks - suppress automatic drawing of axis ticks and labels
- in map projection coordinates. Default False, so parallels and meridians
- can be labelled instead. If parallel or meridian labelling is requested
- (using drawparallels and drawmeridians methods), automatic tick labelling
- will be supressed even is suppress_ticks=False. suppress_ticks=False
- is useful if you want to use your own custom tick formatter, or
- if you want to let matplotlib label the axes in meters
- using native map projection coordinates
-
- anchor - determines how map is placed in axes rectangle (passed to
- axes.set_aspect). Default is 'C', which means map is centered.
- Allowed values are ['C', 'SW', 'S', 'SE', 'E', 'NE', 'N', 'NW', 'W'].
-
- ax - set default axes instance (default None - pylab.gca() may be used
- to get the current axes instance). If you don't want pylab to be imported,
- you can either set this to a pre-defined axes instance, or use the 'ax'
- keyword in each Basemap method call that does drawing. In the first case,
- all Basemap method calls will draw to the same axes instance. In the
- second case, you can draw to different axes with the same Basemap instance.
- You can also use the 'ax' keyword in individual method calls to
- selectively override the default axes instance.
-
- The following parameters are map projection parameters which all default to
- None. Not all parameters are used by all projections, some are ignored.
- The module variable 'projection_params' is a dictionary which
- lists which parameters apply to which projections.
-
- lat_ts - latitude of true scale for mercator projection, optional
- for stereographic projection.
- lat_1 - first standard parallel for lambert conformal, albers
- equal area projection and equidistant conic projections. Latitude of one
- of the two points on the projection centerline for oblique mercator.
- If lat_1 is not given, but lat_0 is, lat_1 is set to lat_0 for
- lambert conformal, albers equal area and equidistant conic.
- lat_2 - second standard parallel for lambert conformal, albers
- equal area projection and equidistant conic projections. Latitude of one
- of the two points on the projection centerline for oblique mercator.
- If lat_2 is not given, it is set to lat_1 for
- lambert conformal, albers equal area and equidistant conic.
- lon_1 - longitude of one of the two points on the projection centerline
- for oblique mercator.
- lon_2 - longitude of one of the two points on the projection centerline
- for oblique mercator.
- no_rot - only used by oblique mercator. If set to True, the map projection
- coordinates will not be rotated to true North. Default is False (projection
- coordinates are automatically rotated).
- lat_0 - central latitude (y-axis origin) - used by all projections,
- Must be equator for mercator projection.
- lon_0 - central meridian (x-axis origin) - used by all projections,
- boundinglat - bounding latitude for pole-centered projections (npstere,spstere,
- nplaea,splaea,npaeqd,spaeqd). These projections are square regions centered
- on the north or south pole. The longitude lon_0 is at 6-o'clock, and the
- latitude circle boundinglat is tangent to the edge of the map at lon_0.
- satellite_height - height of satellite (in m) above equator -
- only relevant for geostationary projections ('geos'). Default 35,786 km.
-
- Here are the most commonly used class methods (see the docstring
- for each for more details):
-
- To draw a graticule grid (labelled latitude and longitude lines)
- use the drawparallels and drawmeridians methods.
-
- To draw coastline, rivers and political boundaries, use the
- the drawcontinents, drawrivers, drawcountries and drawstates methods.
-
- To fill the continents and inland lakes, use the fillcontinents method.
-
- To draw the boundary of the map projection region, and fill the 
- interior a certain color, use the drawmapboundary method.
-
- The contour, contourf, pcolor, pcolormesh, plot, scatter
- quiver and imshow methods use the corresponding matplotlib axes
- methods to draw on the map.
-
- The transform_scalar method can be used to interpolate regular
- lat/lon grids of scalar data to native map projection grids.
-
- The transform_vector method can be used to interpolate and rotate
- regular lat/lon grids of vector data to native map projection grids.
-
- The rotate_vector method rotates a vector field from lat/lon
- coordinates into map projections coordinates, without doing any 
- interpolation.
-
- The readshapefile method can be used to read in data from ESRI
- shapefiles.
-
- The drawgreatcircle method draws great circles on the map.
-""" % locals()
-
-# unsupported projection error message.
-_unsupported_projection = ["'%s' is an unsupported projection.\n"]
-_unsupported_projection.append("The supported projections are:\n")
-_unsupported_projection.append(supported_projections)
-_unsupported_projection = ''.join(_unsupported_projection)
-
-def _validated_ll(param, name, minval, maxval):
- param = float(param)
- if param > maxval or param < minval:
- raise ValueError('%s must be between %f and %f degrees' %
- (name, minval, maxval))
- return param
-
-def _insert_validated(d, param, name, minval, maxval):
- if param is not None:
- d[name] = _validated_ll(param, name, minval, maxval)
-
-class Basemap(object):
- """
- Class for plotting data on map projections with matplotlib.
- See __init__ docstring for details on how to create a class
- instance for a given map projection.
-
- Useful instance variables:
-
- projection - map projection. Print the module variable
- "supported_projections" to see a list.
- aspect - map aspect ratio (size of y dimension / size of x dimension).
- llcrnrlon - longitude of lower left hand corner of the desired map domain.
- llcrnrlon - latitude of lower left hand corner of the desired map domain.
- urcrnrlon - longitude of upper right hand corner of the desired map domain.
- urcrnrlon - latitude of upper right hand corner of the desired map domain.
- llcrnrx,llcrnry,urcrnrx,urcrnry - corners of map domain in projection coordinates.
- rmajor,rminor - equatorial and polar radii of ellipsoid used (in meters).
- resolution - resolution of boundary dataset being used ('c' for crude,
- 'l' for low, etc.). If None, no boundary dataset is associated with the
- Basemap instance.
- srs - a string representing the 'spatial reference system' for the map
- projection as defined by PROJ.4.
-
- Example Usage:
-
- >>> from mpl_toolkits.basemap import Basemap
- >>> import numpy as np
- >>> import matplotlib.pyplot as plt
- >>> import matplotlib.mlab as mlab
- >>> # read in topo data (on a regular lat/lon grid)
- >>> etopo = mlab.load('etopo20data.gz')
- >>> lons = mlab.load('etopo20lons.gz')
- >>> lats = mlab.load('etopo20lats.gz')
- >>> # create Basemap instance for Robinson projection.
- >>> m = Basemap(projection='robin',lon_0=0.5*(lons[0]+lons[-1]))
- >>> # compute native map projection coordinates for lat/lon grid.
- >>> x, y = m(*np.meshgrid(lons,lats))
- >>> # make filled contour plot.
- >>> cs = m.contourf(x,y,etopo,30,cmap=plt.cm.jet)
- >>> m.drawcoastlines() # draw coastlines
- >>> m.drawmapboundary() # draw a line around the map region
- >>> m.drawparallels(np.arange(-90.,120.,30.),labels=[1,0,0,0]) # draw parallels
- >>> m.drawmeridians(np.arange(0.,420.,60.),labels=[0,0,0,1]) # draw meridians
- >>> plt.title('Robinson Projection') # add a title
- >>> plt.show()
-
- [this example (simpletest.py) plus many others can be found in the
- examples directory of source distribution. The "OO" version of this
- example (which does not use pylab) is called "simpletest_oo.py".]
- """
-
- def __init__(self, llcrnrlon=None, llcrnrlat=None,
- urcrnrlon=None, urcrnrlat=None,
- llcrnrx=None, llcrnry=None,
- urcrnrx=None, urcrnry=None,
- width=None, height=None,
- projection='cyl', resolution='c',
- area_thresh=None, rsphere=6370997.0,
- lat_ts=None,
- lat_1=None, lat_2=None,
- lat_0=None, lon_0=None,
- lon_1=None, lon_2=None,
- no_rot=False,
- suppress_ticks=True,
- satellite_height=35786000,
- boundinglat=None,
- anchor='C',
- ax=None):
- # docstring is added after __init__ method definition
-
- # where to put plot in figure (default is 'C' or center)
- self.anchor = anchor
- # map projection.
- self.projection = projection
-
- # set up projection parameter dict.
- projparams = {}
- projparams['proj'] = projection
- try:
- if rsphere[0] > rsphere[1]:
- projparams['a'] = rsphere[0]
- projparams['b'] = rsphere[1]
- else:
- projparams['a'] = rsphere[1]
- projparams['b'] = rsphere[0]
- except:
- if projection == 'tmerc':
- # use bR_a instead of R because of obscure bug
- # in proj4 for tmerc projection.
- projparams['bR_a'] = rsphere
- else:
- projparams['R'] = rsphere
- # set units to meters.
- projparams['units']='m'
- # check for sane values of lon_0, lat_0, lat_ts, lat_1, lat_2
- _insert_validated(projparams, lat_0, 'lat_0', -90, 90)
- _insert_validated(projparams, lat_1, 'lat_1', -90, 90)
- _insert_validated(projparams, lat_2, 'lat_2', -90, 90)
- _insert_validated(projparams, lat_ts, 'lat_ts', -90, 90)
- _insert_validated(projparams, lon_0, 'lon_0', -360, 720)
- _insert_validated(projparams, lon_1, 'lon_1', -360, 720)
- _insert_validated(projparams, lon_2, 'lon_2', -360, 720)
- if projection == 'geos':
- projparams['h'] = satellite_height
- # check for sane values of projection corners.
- using_corners = (None not in [llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat])
- if using_corners:
- self.llcrnrlon = _validated_ll(llcrnrlon, 'llcrnrlon', -360, 720)
- self.urcrnrlon = _validated_ll(urcrnrlon, 'urcrnrlon', -360, 720)
- self.llcrnrlat = _validated_ll(llcrnrlat, 'llcrnrlat', -90, 90)
- self.urcrnrlat = _validated_ll(urcrnrlat, 'urcrnrlat', -90, 90)
-
- # for each of the supported projections,
- # compute lat/lon of domain corners
- # and set values in projparams dict as needed.
-
- if projection in ['lcc', 'eqdc', 'aea']:
- # if lat_0 is given, but not lat_1,
- # set lat_1=lat_0
- if lat_1 is None and lat_0 is not None:
- lat_1 = lat_0
- projparams['lat_1'] = lat_1
- if lat_1 is None or lon_0 is None:
- raise ValueError('must specify lat_1 or lat_0 and lon_0 for %s basemap (lat_2 is optional)' % _projnames[projection])
- if lat_2 is None:
- projparams['lat_2'] = lat_1
- if not using_corners:
- if width is None or height is None:
- raise ValueError, 'must either specify lat/lon values of corners (llcrnrlon,llcrnrlat,ucrnrlon,urcrnrlat) in degrees or width and height in meters'
- if lon_0 is None or lat_0 is None:
- raise ValueError, 'must specify lon_0 and lat_0 when using width, height to specify projection region'
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat = _choosecorners(width,height,**projparams)
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection == 'stere':
- if lat_0 is None or lon_0 is None:
- raise ValueError, 'must specify lat_0 and lon_0 for Stereographic basemap (lat_ts is optional)'
- if not using_corners:
- if width is None or height is None:
- raise ValueError, 'must either specify lat/lon values of corners (llcrnrlon,llcrnrlat,ucrnrlon,urcrnrlat) in degrees or width and height in meters'
- if lon_0 is None or lat_0 is None:
- raise ValueError, 'must specify lon_0 and lat_0 when using width, height to specify projection region'
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat = _choosecorners(width,height,**projparams)
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection in ['spstere', 'npstere',
- 'splaea', 'nplaea',
- 'spaeqd', 'npaeqd']:
- if boundinglat is None or lon_0 is None:
- raise ValueError('must specify boundinglat and lon_0 for %s basemap' % _projnames[projection])
- if projection[0] == 's':
- sgn = -1
- else:
- sgn = 1
- rootproj = projection[2:]
- projparams['proj'] = rootproj
- if rootproj == 'stere':
- projparams['lat_ts'] = sgn * 90.
- projparams['lat_0'] = sgn * 90.
- self.llcrnrlon = lon_0 - sgn*45.
- self.urcrnrlon = lon_0 + sgn*135.
- proj = pyproj.Proj(projparams)
- x,y = proj(lon_0,boundinglat)
- lon,self.llcrnrlat = proj(math.sqrt(2.)*y,0.,inverse=True)
- self.urcrnrlat = self.llcrnrlat
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % _projnames[projection]
- elif projection == 'laea':
- if lat_0 is None or lon_0 is None:
- raise ValueError, 'must specify lat_0 and lon_0 for Lambert Azimuthal basemap'
- if not using_corners:
- if width is None or height is None:
- raise ValueError, 'must either specify lat/lon values of corners (llcrnrlon,llcrnrlat,ucrnrlon,urcrnrlat) in degrees or width and height in meters'
- if lon_0 is None or lat_0 is None:
- raise ValueError, 'must specify lon_0 and lat_0 when using width, height to specify projection region'
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat = _choosecorners(width,height,**projparams)
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection == 'merc':
- if lat_ts is None:
- raise ValueError, 'must specify lat_ts for Mercator basemap'
- # clip plot region to be within -89.99S to 89.99N
- # (mercator is singular at poles)
- if not using_corners:
- llcrnrlon = -180.
- llcrnrlat = -90.
- urcrnrlon = 180
- urcrnrlat = 90.
- if llcrnrlat < -89.99: llcrnrlat = -89.99
- if llcrnrlat > 89.99: llcrnrlat = 89.99
- if urcrnrlat < -89.99: urcrnrlat = -89.99
- if urcrnrlat > 89.99: urcrnrlat = 89.99
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % self.projection
- elif projection in ['tmerc','gnom','cass','poly'] :
- if lat_0 is None or lon_0 is None:
- raise ValueError, 'must specify lat_0 and lon_0 for Transverse Mercator, Gnomonic, Cassini-Soldnerr Polyconic basemap'
- if not using_corners:
- if width is None or height is None:
- raise ValueError, 'must either specify lat/lon values of corners (llcrnrlon,llcrnrlat,ucrnrlon,urcrnrlat) in degrees or width and height in meters'
- if lon_0 is None or lat_0 is None:
- raise ValueError, 'must specify lon_0 and lat_0 when using width, height to specify projection region'
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat = _choosecorners(width,height,**projparams)
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection == 'ortho':
- if not projparams.has_key('R'):
- raise ValueError, 'orthographic projection only works for perfect spheres - not ellipsoids'
- if lat_0 is None or lon_0 is None:
- raise ValueError, 'must specify lat_0 and lon_0 for Orthographic basemap'
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % self.projection
- if not using_corners:
- llcrnrlon = -180.
- llcrnrlat = -90.
- urcrnrlon = 180
- urcrnrlat = 90.
- self._fulldisk = True
- else:
- self._fulldisk = False
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- # FIXME: won't work for points exactly on equator??
- if np.abs(lat_0) < 1.e-2: lat_0 = 1.e-2
- projparams['lat_0'] = lat_0
- elif projection == 'geos':
- if lon_0 is None:
- raise ValueError, 'must specify lon_0 for Geostationary basemap'
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % self.projection
- if not using_corners:
- llcrnrlon = -180.
- llcrnrlat = -90.
- urcrnrlon = 180
- urcrnrlat = 90.
- self._fulldisk = True
- else:
- self._fulldisk = False
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection in ['moll','robin','sinu']:
- if lon_0 is None:
- raise ValueError, 'must specify lon_0 for Robinson, Mollweide, or Sinusoidal basemap'
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % self.projection
- llcrnrlon = -180.
- llcrnrlat = -90.
- urcrnrlon = 180
- urcrnrlat = 90.
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection == 'omerc':
- if lat_1 is None or lon_1 is None or lat_2 is None or lon_2 is None:
- raise ValueError, 'must specify lat_1,lon_1 and lat_2,lon_2 for Oblique Mercator basemap'
- projparams['lat_1'] = lat_1
- projparams['lon_1'] = lon_1
- projparams['lat_2'] = lat_2
- projparams['lon_2'] = lon_2
- projparams['lat_0'] = lat_0
- if no_rot:
- projparams['no_rot']=''
- #if not using_corners:
- # raise ValueError, 'cannot specify map region with width and height keywords for this projection, please specify lat/lon values of corners'
- if not using_corners:
- if width is None or height is None:
- raise ValueError, 'must either specify lat/lon values of corners (llcrnrlon,llcrnrlat,ucrnrlon,urcrnrlat) in degrees or width and height in meters'
- if lon_0 is None or lat_0 is None:
- raise ValueError, 'must specify lon_0 and lat_0 when using width, height to specify projection region'
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat = _choosecorners(width,height,**projparams)
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection == 'aeqd':
- if lat_0 is None or lon_0 is None:
- raise ValueError, 'must specify lat_0 and lon_0 for Azimuthal Equidistant basemap'
- if not using_corners:
- if width is None or height is None:
- raise ValueError, 'must either specify lat/lon values of corners (llcrnrlon,llcrnrlat,ucrnrlon,urcrnrlat) in degrees or width and height in meters'
- if lon_0 is None or lat_0 is None:
- raise ValueError, 'must specify lon_0 and lat_0 when using width, height to specify projection region'
- llcrnrlon,llcrnrlat,urcrnrlon,urcrnrlat = _choosecorners(width,height,**projparams)
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- elif projection == 'mill':
- if not using_corners:
- llcrnrlon = -180.
- llcrnrlat = -90.
- urcrnrlon = 180
- urcrnrlat = 90.
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % self.projection
- elif projection == 'cyl':
- if not using_corners:
- llcrnrlon = -180.
- llcrnrlat = -90.
- urcrnrlon = 180
- urcrnrlat = 90.
- self.llcrnrlon = llcrnrlon; self.llcrnrlat = llcrnrlat
- self.urcrnrlon = urcrnrlon; self.urcrnrlat = urcrnrlat
- if width is not None or height is not None:
- print 'warning: width and height keywords ignored for %s projection' % self.projection
- else:
- raise ValueError(_unsupported_projection % projection)
-
- # initialize proj4
- proj = Proj(projparams,self.llcrnrlon,self.llcrnrlat,self.urcrnrlon,self.urcrnrlat)
-
- # make sure axis ticks are suppressed.
- self.noticks = suppress_ticks
-
- # make Proj instance a Basemap instance variable.
- self.projtran = proj
- # copy some Proj attributes.
- atts = ['rmajor','rminor','esq','flattening','ellipsoid','projparams']
- for att in atts:
- self.__dict__[att] = proj.__dict__[att]
- # these only exist for geostationary projection.
- if hasattr(proj,'_width'):
- self.__dict__['_width'] = proj.__dict__['_width']
- if hasattr(proj,'_height'):
- self.__dict__['_height'] = proj.__dict__['_height']
- # spatial reference string (useful for georeferencing output
- # images with gdal_translate).
- if hasattr(self,'_proj4'):
- self.srs = proj._proj4.srs
- else:
- pjargs = []
- for key,value in self.projparams.iteritems():
- # 'cyl' projection translates to 'eqc' in PROJ.4
- if projection == 'cyl' and key == 'proj':
- value = 'eqc'
- # ignore x_0 and y_0 settings for 'cyl' projection
- # (they are not consistent with what PROJ.4 uses)
- elif projection == 'cyl' and key in ['x_0','y_0']:
- continue
- pjargs.append('+'+key+"="+str(value)+' ')
- self.srs = ''.join(pjargs)
- # set instance variables defining map region.
- self.xmin = proj.xmin
- self.xmax = proj.xmax
- self.ymin = proj.ymin
- self.ymax = proj.ymax
- if projection == 'cyl':
- self.aspect = (self.urcrnrlat-self.llcrnrlat)/(self.urcrnrlon-self.llcrnrlon)
- else:
- self.aspect = (proj.ymax-proj.ymin)/(proj.xmax-proj.xmin)
- if projection in ['geos','ortho'] and \
- None not in [llcrnrx,llcrnry,urcrnrx,urcrnry]:
- self.llcrnrx = llcrnrx+0.5*proj.xmax
- self.llcrnry = llcrnry+0.5*proj.ymax
- self.urcrnrx = urcrnrx+0.5*proj.xmax
- self.urcrnry = urcrnry+0.5*proj.ymax
- self._fulldisk = False
- else:
- self.llcrnrx = proj.llcrnrx
- self.llcrnry = proj.llcrnry
- self.urcrnrx = proj.urcrnrx
- self.urcrnry = proj.urcrnry
- # set min/max lats for projection domain.
- if projection in ['mill','cyl','merc']:
- self.latmin = self.llcrnrlat
- self.latmax = self.urcrnrlat
- elif projection in ['ortho','geos','moll','robin','sinu']:
- self.latmin = -90.
- self.latmax = 90.
- else:
- lons, lats = self.makegrid(101,101)
- self.latmin = lats.min()
- self.latmax = lats.max()
-
- # if ax == None, pyplot.gca may be used.
- self.ax = ax
- self.lsmask = None
-
- # set defaults for area_thresh.
- self.resolution = resolution
- if area_thresh is None and resolution is not None:
- if resolution == 'c':
- area_thresh = 10000.
- elif resolution == 'l':
- area_thresh = 1000.
- elif resolution == 'i':
- area_thresh = 100.
- elif resolution == 'h':
- area_thresh = 10.
- elif resolution == 'f':
- area_thresh = 1.
- else:
- raise ValueError, "boundary resolution must be one of 'c','l','i','h' or 'f'"
- self.area_thresh = area_thresh
- # define map boundary polygon (in lat/lon coordinates)
- self._boundarypolyll, self._boundarypolyxy = self._getmapboundary()
- # read in coastline polygons, only keeping those that
- # intersect map boundary polygon.
- if self.resolution is not None:
- self.coastsegs, self.coastpolygontypes = self._readboundarydata('gshhs')
- # reformat for use in matplotlib.patches.Polygon.
- self.coastpolygons = []
- # also, split coastline segments that jump across entire plot.
- coastsegs = []
- for seg in self.coastsegs:
- x, y = zip(*seg)
- self.coastpolygons.append((x,y))
- x = np.array(x,np.float64); y = np.array(y,np.float64)
- xd = (x[1:]-x[0:-1])**2
- yd = (y[1:]-y[0:-1])**2
- dist = np.sqrt(xd+yd)
- split = dist > 5000000.
- if np.sum(split) and self.projection not in ['merc','cyl','mill']:
- ind = (np.compress(split,np.squeeze(split*np.indices(xd.shape)))+1).tolist()
- iprev = 0
- ind.append(len(xd))
- for i in ind:
- # don't add empty lists.
- if len(range(iprev,i)): 
- coastsegs.append(zip(x[iprev:i],y[iprev:i]))
- iprev = i
- else:
- coastsegs.append(seg)
- self.coastsegs = coastsegs
- # set __init__'s docstring
- __init__.__doc__ = _Basemap_init_doc
-
- def __call__(self,x,y,inverse=False):
- """
- Calling a Basemap class instance with the arguments lon, lat will
- convert lon/lat (in degrees) to x/y native map projection
- coordinates (in meters). If optional keyword 'inverse' is
- True (default is False), the inverse transformation from x/y
- to lon/lat is performed.
-
- For cylindrical equidistant projection ('cyl'), this
- does nothing (i.e. x,y == lon,lat).
-
- For non-cylindrical projections, the inverse transformation
- always returns longitudes between -180 and 180 degrees. For
- cylindrical projections (self.projection == 'cyl','mill' or 'merc')
- the inverse transformation will return longitudes between
- self.llcrnrlon and self.llcrnrlat.
-
- input arguments lon, lat can be either scalar floats or N arrays.
- """
- return self.projtran(x,y,inverse=inverse)
-
- def makegrid(self,nx,ny,returnxy=False):
- """
- return arrays of shape (ny,nx) containing lon,lat coordinates of
- an equally spaced native projection grid.
- if returnxy = True, the x,y values of the grid are returned also.
- """
- return self.projtran.makegrid(nx,ny,returnxy=returnxy)
-
- def _readboundarydata(self,name):
- """
- read boundary data, clip to map projection region.
- """
- msg = dedent("""
- Unable to open boundary dataset file. Only the 'crude', 'low',
- 'intermediate' and 'high' resolution datasets are installed by default.
- If you are requesting a 'full' resolution dataset, you may need to
- download and install those files separately
- (see the basemap README for details).""")
- try:
- bdatfile = open(os.path.join(basemap_datadir,name+'_'+self.resolution+'.dat'),'rb')
- bdatmetafile = open(os.path.join(basemap_datadir,name+'meta_'+self.resolution+'.dat'),'r')
- except:
- raise IOError, msg
- polygons = []
- polygon_types = []
- # coastlines are polygons, other boundaries are line segments.
- if name == 'gshhs':
- Shape = _geoslib.Polygon
- else:
- Shape = _geoslib.LineString
- # see if map projection region polygon contains a pole.
- NPole = _geoslib.Point(self(0.,90.))
- SPole = _geoslib.Point(self(0.,-90.))
- boundarypolyxy = self._boundarypolyxy
- boundarypolyll = self._boundarypolyll
- hasNP = NPole.within(boundarypolyxy)
- hasSP = SPole.within(boundarypolyxy)
- containsPole = hasNP or hasSP
- # these projections cannot cross pole.
- if containsPole and\
- self.projection in ['merc','mill','cyl','robin','moll','sinu','geos']:
- #self.projection in ['tmerc','omerc','cass','merc','mill','cyl','robin','moll','sinu','geos']:
- raise ValueError('%s projection cannot cross pole'%(self.projection))
- # make sure orthographic projection has containsPole=True
- # we will compute the intersections in stereographic
- # coordinates, then transform to orthographic.
- if self.projection == 'ortho' and name == 'gshhs':
- containsPole = True
- lon_0=self.projparams['lon_0']
- lat_0=self.projparams['lat_0']
- re = self.projparams['R']
- # center of stereographic projection restricted to be 
- # nearest one of 6 points on the sphere (every 90 deg lat/lon).
- lon0 = 90.*(np.around(lon_0/90.))
- lat0 = 90.*(np.around(lat_0/90.))
- if np.abs(int(lat0)) == 90: lon0=0.
- maptran = pyproj.Proj(proj='stere',lon_0=lon0,lat_0=lat0,R=re)
- # boundary polygon for orthographic projection
- # in stereographic coorindates.
- b = self._boundarypolyll.boundary
- blons = b[:,0]; blats = b[:,1]
- b[:,0], b[:,1] = maptran(blons, blats)
- boundarypolyxy = _geoslib.Polygon(b)
- for line in bdatmetafile:
- linesplit = line.split()
- area = float(linesplit[1])
- south = float(linesplit[3])
- north = float(linesplit[4])
- if area < 0.: area = 1.e30
- useit = self.latmax>=south and self.latmin<=north and area>self.area_thresh
- if useit:
- type = int(linesplit[0])
- npts = int(linesplit[2])
- offsetbytes = int(linesplit[5])
- bytecount = int(linesplit[6])
- bdatfile.seek(offsetbytes,0)
- # read in binary string convert into an npts by 2
- # numpy array (first column is lons, second is lats).
- polystring = bdatfile.read(bytecount)
- # binary data is little endian.
- b = np.array(np.fromstring(polystring,dtype='<f4'),'f8')
- b.shape = (npts,2)
- b2 = b.copy()
- # if map boundary polygon is a valid one in lat/lon
- # coordinates (i.e. it does not contain either pole),
- # the intersections of the boundary geometries
- # and the map projection region can be computed before
- # transforming the boundary geometry to map projection
- # coordinates (this saves time, especially for small map
- # regions and high-resolution boundary geometries).
- if not containsPole:
- # close Antarctica.
- if name == 'gshhs' and south < -68 and area > 10000:
- lons = b[:,0]
- lats = b[:,1]
- lons2 = lons[:-2][::-1]
- lats2 = lats[:-2][::-1]
- lons1 = lons2 - 360.
- lons3 = lons2 + 360.
- lons = lons1.tolist()+lons2.tolist()+lons3.tolist()
- lats = lats2.tolist()+lats2.tolist()+lats2.tolist()
- lonstart,latstart = lons[0], lats[0]
- lonend,latend = lons[-1], lats[-1]
- lons.insert(0,lonstart)
- lats.insert(0,-90.)
- lons.append(lonend)
- lats.append(-90.)
- b = np.empty((len(lons),2),np.float64)
- b[:,0] = lons; b[:,1] = lats
- poly = _geoslib.Polygon(b)
- antart = True
- else:
- poly = Shape(b)
- antart = False
- # create duplicate polygons shifted by -360 and +360
- # (so as to properly treat polygons that cross
- # Greenwich meridian).
- if not antart:
- b2[:,0] = b[:,0]-360
- poly1 = Shape(b2)
- b2[:,0] = b[:,0]+360
- poly2 = Shape(b2)
- polys = [poly1,poly,poly2]
- else: # Antartica already extends from -360 to +720.
- polys = [poly]
- for poly in polys:
- # if polygon instersects map projection
- # region, process it.
- if poly.intersects(boundarypolyll):
- # if geometry intersection calculation fails,
- # just move on.
- try:
- geoms = poly.intersection(boundarypolyll)
- except:
- continue
- # iterate over geometries in intersection.
- for psub in geoms:
- # only coastlines are polygons,
- # which have a 'boundary' attribute.
- # otherwise, use 'coords' attribute
- # to extract coordinates.
- b = psub.boundary
- blons = b[:,0]; blats = b[:,1]
- # transformation from lat/lon to
- # map projection coordinates.
- bx, by = self(blons, blats)
- polygons.append(zip(bx,by))
- polygon_types.append(type)
- # if map boundary polygon is not valid in lat/lon
- # coordinates, compute intersection between map
- # projection region and boundary geometries in map
- # projection coordinates.
- else:
- # transform coordinates from lat/lon
- # to map projection coordinates.
- # special case for ortho, compute coastline polygon
- # vertices in stereographic coords.
- if name == 'gshhs' and self.projection == 'ortho':
- b[:,0], b[:,1] = maptran(b[:,0], b[:,1])
- else:
- b[:,0], b[:,1] = self(b[:,0], b[:,1])
- goodmask = np.logical_and(b[:,0]<1.e20,b[:,1]<1.e20)
- # if less than two points are valid in
- # map proj coords, skip this geometry.
- if np.sum(goodmask) <= 1: continue
- if name != 'gshhs':
- # if not a polygon,
- # just remove parts of geometry that are undefined
- # in this map projection.
- bx = np.compress(goodmask, b[:,0])
- by = np.compress(goodmask, b[:,1])
- # for orthographic projection, all points
- # outside map projection region are eliminated
- # with the above step, so we're done.
- if self.projection == 'ortho':
- polygons.append(zip(bx,by))
- polygon_types.append(type)
- continue
- # create a GEOS geometry object.
- poly = Shape(b)
- # if geometry instersects map projection
- # region, and doesn't have any invalid points, process it.
- if goodmask.all() and poly.intersects(boundarypolyxy):
- # if geometry intersection calculation fails,
- # just move on.
- try:
- geoms = poly.intersection(boundarypolyxy)
- except:
- continue
- # iterate over geometries in intersection.
- for psub in geoms:
- b = psub.boundary
- # if projection == 'ortho',
- # transform polygon from stereographic
- # to orthographic coordinates.
- if self.projection == 'ortho':
- # if coastline polygon covers more than 99%
- # of map region for fulldisk projection,
- # it's probably bogus, so skip it.
- areafrac = psub.area()/boundarypolyxy.area()
- if name == 'gshhs' and\
- self._fulldisk and\
- areafrac > 0.99: continue
- # inverse transform from stereographic
- # to lat/lon.
- b[:,0], b[:,1] = maptran(b[:,0], b[:,1], inverse=True)
- # orthographic.
- b[:,0], b[:,1]= self(b[:,0], b[:,1])
- polygons.append(zip(b[:,0],b[:,1]))
- polygon_types.append(type)
- return polygons, polygon_types
-
- def _getmapboundary(self):
- """
- create map boundary polygon (in lat/lon and x/y coordinates)
- """
- nx = 100
- ny = 100
- maptran = self
- if self.projection in ['ortho','geos']:
- # circular region.
- thetas = np.linspace(0.,2.*np.pi,2*nx*ny)[:-1]
- if self.projection == 'ortho':
- rminor = self.rmajor
- rmajor = self.rmajor
- else:
- rminor = self._height
- rmajor = self._width
- x = rmajor*np.cos(thetas) + rmajor
- y = rminor*np.sin(thetas) + rminor
- b = np.empty((len(x),2),np.float64)
- b[:,0]=x; b[:,1]=y
- boundaryxy = _geoslib.Polygon(b)
- # compute proj instance for full disk, if necessary.
- if not self._fulldisk:
- projparms = self.projparams.copy()
- del projparms['x_0']
- del projparms['y_0']
- if self.projection == 'ortho':
- llcrnrx = -self.rmajor
- llcrnry = -self.rmajor
- urcrnrx = -llcrnrx
- urcrnry = -llcrnry
- else:
- llcrnrx = -self._width
- llcrnry = -self._height
- urcrnrx = -llcrnrx
- urcrnry = -llcrnry
- projparms['x_0']=-llcrnrx
- projparms['y_0']=-llcrnry
- maptran = pyproj.Proj(projparms)
- elif self.projection in ['moll','robin','sinu']:
- # quasi-elliptical region.
- lon_0 = self.projparams['lon_0']
- # left side
- lats1 = np.linspace(-89.9,89.9,ny).tolist()
- lons1 = len(lats1)*[lon_0-179.9]
- # top.
- lons2 = np.linspace(lon_0-179.9,lon_0+179.9,nx).tolist()
- lats2 = len(lons2)*[89.9]
- # right side
- lats3 = np.linspace(89.9,-89.9,ny).tolist()
- lons3 = len(lats3)*[lon_0+179.9]
- # bottom.
- lons4 = np.linspace(lon_0+179.9,lon_0-179.9,nx).tolist()
- lats4 = len(lons4)*[-89.9]
- lons = np.array(lons1+lons2+lons3+lons4,np.float64)
- lats = np.array(lats1+lats2+lats3+lats4,np.float64)
- x, y = maptran(lons,lats)
- b = np.empty((len(x),2),np.float64)
- b[:,0]=x; b[:,1]=y
- boundaryxy = _geoslib.Polygon(b)
- else: # all other projections are rectangular.
- # left side (x = xmin, ymin <= y <= ymax)
- yy = np.linspace(self.ymin, self.ymax, ny)[:-1]
- x = len(yy)*[self.xmin]; y = yy.tolist()
- # top (y = ymax, xmin <= x <= xmax)
- xx = np.linspace(self.xmin, self.xmax, nx)[:-1]
- x = x + xx.tolist()
- y = y + len(xx)*[self.ymax]
- # right side (x = xmax, ymin <= y <= ymax)
- yy = np.linspace(self.ymax, self.ymin, ny)[:-1]
- x = x + len(yy)*[self.xmax]; y = y + yy.tolist()
- # bottom (y = ymin, xmin <= x <= xmax)
- xx = np.linspace(self.xmax, self.xmin, nx)[:-1]
- x = x + xx.tolist()
- y = y + len(xx)*[self.ymin]
- x = np.array(x,np.float64)
- y = np.array(y,np.float64)
- b = np.empty((4,2),np.float64)
- b[:,0]=[self.xmin,self.xmin,self.xmax,self.xmax]
- b[:,1]=[self.ymin,self.ymax,self.ymax,self.ymin]
- boundaryxy = _geoslib.Polygon(b)
- if self.projection in ['mill','merc','cyl']:
- # make sure map boundary doesn't quite include pole.
- if self.urcrnrlat > 89.9999:
- urcrnrlat = 89.9999
- else:
- urcrnrlat = self.urcrnrlat
- if self.llcrnrlat < -89.9999:
- llcrnrlat = -89.9999
- else:
- llcrnrlat = self.llcrnrlat
- lons = [self.llcrnrlon, self.llcrnrlon, self.urcrnrlon, self.urcrnrlon]
- lats = [llcrnrlat, urcrnrlat, urcrnrlat, llcrnrlat]
- x, y = self(lons, lats)
- b = np.empty((len(x),2),np.float64)
- b[:,0]=x; b[:,1]=y
- boundaryxy = _geoslib.Polygon(b)
- else:
- if self.projection not in ['moll','robin','sinu']:
- lons, lats = maptran(x,y,inverse=True)
- # fix lons so there are no jumps.
- n = 1
- lonprev = lons[0]
- for lon,lat in zip(lons[1:],lats[1:]):
- if np.abs(lon-lonprev) > 90.:
- if lonprev < 0:
- lon = lon - 360.
- else:
- lon = lon + 360
- lons[n] = lon
- lonprev = lon
- n = n + 1
- b = np.empty((len(lons),2),np.float64)
- b[:,0]=lons; b[:,1]=lats
- boundaryll = _geoslib.Polygon(b)
- return boundaryll, boundaryxy
-
-
- def drawmapboundary(self,color='k',linewidth=1.0,fill_color=None,\
- zorder=None,ax=None):
- """
- draw boundary around map projection region, optionally
- filling interior of region.
-
- linewidth - line width for boundary (default 1.)
- color - color of boundary line (default black)
- fill_color - fill the map region background with this
- color (default is no fill or fill with axis background color).
- zorder - sets the zorder for filling map background
- (default 0).
- ax - axes instance to use (default None, use default axes 
- instance).
- returns PatchCollection representing map boundary.
- """
- # get current axes instance (if none specified).
- if ax is None and self.ax is None:
- try:
- ax = plt.gca()
- except:
- import matplotlib.pyplot as plt
- ax = plt.gca()
- elif ax is None and self.ax is not None:
- ax = self.ax
- limb = None
- if self.projection == 'ortho':
- limb = Circle((self.rmajor,self.rmajor),self.rmajor)
- elif self.projection == 'geos':
- limb = Ellipse((self._width,self._height),2.*self._width,2.*self._height)
- if self.projection in ['ortho','geos'] and self._fulldisk:
- # elliptical region.
- ax.add_patch(limb)
- if fill_color is None:
- limb.set_fill(False)
- else:
- limb.set_facecolor(fill_color)
- limb.set_zorder(0)
- limb.set_edgecolor(color)
- limb.set_linewidth(linewidth)
- limb.set_clip_on(False)
- if zorder is not None:
- limb.set_zorder(zorder)
- elif self.projection in ['moll','robin','sinu']: # elliptical region.
- nx = 100; ny = 100
- # quasi-elliptical region.
- lon_0 = self.projparams['lon_0']
- # left side
- lats1 = np.linspace(-89.9,89.9,ny).tolist()
- lons1 = len(lats1)*[lon_0-179.9]
- # top.
- lons2 = np.linspace(lon_0-179.9,lon_0+179.9,nx).tolist()
- lats2 = len(lons2)*[89.9]
- # right side
- lats3 = np.linspace(89.9,-89.9,ny).tolist()
- lons3 = len(lats3)*[lon_0+179.9]
- # bottom.
- lons4 = np.linspace(lon_0+179.9,lon_0-179.9,nx).tolist()
- lats4 = len(lons4)*[-89.9]
- lons = np.array(lons1+lons2+lons3+lons4,np.float64)
- lats = np.array(lats1+lats2+lats3+lats4,np.float64)
- x, y = self(lons,lats)
- xy = zip(x,y)
- limb = Polygon(xy,edgecolor=color,linewidth=linewidth)
- ax.add_patch(limb)
- if fill_color is None:
- limb.set_fill(False)
- else:
- limb.set_facecolor(fill_color)
- limb.set_zorder(0)
- limb.set_clip_on(False)
- if zorder is not None:
- limb.set_zorder(zorder)
- else: # all other projections are rectangular.
- ax.axesPatch.set_linewidth(linewidth)
- if self.projection not in ['geos','ortho']:
- if fill_color is None:
- ax.axesPatch.set_facecolor(ax.get_axis_bgcolor())
- else:
- ax.axesPatch.set_facecolor(fill_color)
- ax.axesPatch.set_zorder(0)
- ax.axesPatch.set_edgecolor(color)
- ax.set_frame_on(True)
- if zorder is not None:
- ax.axesPatch.set_zorder(zorder)
- else:
- ax.axesPatch.set_facecolor(ax.get_axis_bgcolor())
- ax.axesPatch.set_edgecolor(color)
- ax.set_frame_on(True)
- if zorder is not None:
- ax.axesPatch.set_zorder(zorder)
- # for geos or ortho projections, also
- # draw and fill map projection limb, clipped
- # to rectangular region.
- ax.add_patch(limb)
- if fill_color is None:
- limb.set_fill(False)
- else:
- limb.set_facecolor(fill_color)
- limb.set_zorder(0)
- limb.set_edgecolor(color)
- limb.set_linewidth(linewidth)
- if zorder is not None:
- limb.set_zorder(zorder)
- limb.set_clip_on(True)
- # set axes limits to fit map region.
- self.set_axes_limits(ax=ax)
- return limb
-
- def fillcontinents(self,color='0.8',lake_color=None,ax=None,zorder=None):
- """
- Fill continents.
-
- color - color to fill continents (default gray).
- lake_color - color to fill inland lakes (default axes background).
- ax - axes instance (overrides default axes instance).
- zorder - sets the zorder for the continent polygons (if not specified,
- uses default zorder for a Polygon patch). Set to zero if you want to paint
- over the filled continents).
-
- After filling continents, lakes are re-filled with axis background color.
-
- returns Polygon object.
- """
- if self.resolution is None:
- raise AttributeError, 'there are no boundary datasets associated with this Basemap instance'
- # get current axes instance (if none specified).
- if ax is None and self.ax is None:
- try:
- ax = plt.gca()
- except:
- import matplotlib.pyplot as plt
- ax = plt.gca()
- elif ax is None and self.ax is not None:
- ax = self.ax
- # get axis background color.
- axisbgc = ax.get_axis_bgcolor()
- npoly = 0
- for x,y in self.coastpolygons:
- xa = np.array(x,np.float32)
- ya = np.array(y,np.float32)
- # check to see if all four corners of domain in polygon (if so,
- # don't draw since it will just fill in the whole map).
- delx = 10; dely = 10
- if self.projection in ['cyl']:
- delx = 0.1
- dely = 0.1
- test1 = np.fabs(xa-self.urcrnrx) < delx
- test2 = np.fabs(xa-self.llcrnrx) < delx
- test3 = np.fabs(ya-self.urcrnry) < dely
- test4 = np.fabs(ya-self.llcrnry) < dely
- hasp1 = np.sum(test1*test3)
- hasp2 = np.sum(test2*test3)
- hasp4 = np.sum(test2*test4)
- hasp3 = np.sum(test1*test4)
- if not hasp1 or not hasp2 or not ...
 
[truncated message content]

Revision: 5546
 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=5546&view=rev
Author: jswhit
Date: 2008年06月15日 04:57:51 -0700 (2008年6月15日)
Log Message:
-----------
finished cleanup of docstrings so sphinx-generated API docs look nice.
Modified Paths:
--------------
 trunk/toolkits/basemap/lib/mpl_toolkits/basemap/__init__.py
Modified: trunk/toolkits/basemap/lib/mpl_toolkits/basemap/__init__.py
===================================================================
--- trunk/toolkits/basemap/lib/mpl_toolkits/basemap/__init__.py	2008年06月14日 21:14:34 UTC (rev 5545)
+++ trunk/toolkits/basemap/lib/mpl_toolkits/basemap/__init__.py	2008年06月15日 11:57:51 UTC (rev 5546)
@@ -2391,6 +2391,8 @@
 (see matplotlib.pyplot.scatter documentation).
 
 Extra keyword ``ax`` can be used to override the default axes instance.
+
+ Other \**kwargs passed on to matplotlib.pyplot.scatter.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2427,6 +2429,8 @@
 (see matplotlib.pyplot.plot documentation).
 
 Extra keyword ``ax`` can be used to override the default axis instance.
+
+ Other \**kwargs passed on to matplotlib.pyplot.plot.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2466,6 +2470,8 @@
 will be drawn over map region.
 
 Extra keyword ``ax`` can be used to override the default axis instance.
+
+ Other \**kwargs passed on to matplotlib.pyplot.plot.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2507,15 +2513,16 @@
 
 def pcolor(self,x,y,data,**kwargs):
 """
- Make a pseudo-color plot over the map.
+ Make a pseudo-color plot over the map
+ (see matplotlib.pyplot.pcolor documentation).
 
- see matplotlib.pyplot.pcolor documentation for definition of \**kwargs
-
 If x or y are outside projection limb (i.e. they have values > 1.e20)
 they will be convert to masked arrays with those values masked.
 As a result, those values will not be plotted.
 
- extra keyword 'ax' can be used to override the default axis instance.
+ Extra keyword ``ax`` can be used to override the default axis instance.
+
+ Other \**kwargs passed on to matplotlib.pyplot.pcolor.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2557,11 +2564,12 @@
 
 def pcolormesh(self,x,y,data,**kwargs):
 """
- Make a pseudo-color plot over the map.
+ Make a pseudo-color plot over the map
+ (see matplotlib.pyplot.pcolormesh documentation).
 
- see matplotlib.pyplot.pcolormesh documentation for definition of \**kwargs
+ Extra keyword ``ax`` can be used to override the default axis instance.
 
- extra keyword 'ax' can be used to override the default axis instance.
+ Other \**kwargs passed on to matplotlib.pyplot.pcolormesh.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2599,9 +2607,12 @@
 
 def contour(self,x,y,data,*args,**kwargs):
 """
- Make a contour plot over the map (see matplotlib.pyplot.contour documentation).
+ Make a contour plot over the map 
+ (see matplotlib.pyplot.contour documentation).
 
- extra keyword 'ax' can be used to override the default axis instance.
+ Extra keyword ``ax`` can be used to override the default axis instance.
+
+ Other \*args and \**kwargs passed on to matplotlib.pyplot.contour.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2666,11 +2677,15 @@
 
 def contourf(self,x,y,data,*args,**kwargs):
 """
- Make a filled contour plot over the map (see matplotlib.pyplot.contourf documentation).
+ Make a filled contour plot over the map
+ (see matplotlib.pyplot.contourf documentation).
+
 If x or y are outside projection limb (i.e. they have values > 1.e20),
 the corresponing data elements will be masked.
 
 Extra keyword 'ax' can be used to override the default axis instance.
+
+ Other \*args and \**kwargs passed on to matplotlib.pyplot.scatter.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2736,11 +2751,11 @@
 def quiver(self, x, y, u, v, *args, **kwargs):
 """
 Make a vector plot (u, v) with arrows on the map.
+ (see matplotlib.pyplot.quiver documentation).
 
- Extra arguments (\*args and \**kwargs) passed to quiver Axes method (see
- matplotlib.pyplot.quiver documentation for details).
+ Extra keyword ``ax`` can be used to override the default axis instance.
 
- extra keyword 'ax' can be used to override the default axis instance.
+ Other \*args and \**kwargs passed on to matplotlib.pyplot.quiver.
 """
 if not kwargs.has_key('ax') and self.ax is None:
 try:
@@ -2774,38 +2789,53 @@
 def drawlsmask(self,rgba_land,rgba_ocean,lsmask=None,
 lsmask_lons=None,lsmask_lats=None,lakes=False,**kwargs):
 """
- draw land-sea mask image.
+ Draw land-sea mask image.
 
- *Note* the land-sea mask image cannot be overlaid on top
- of other images, due to limitations in matplotlib image handling.
+ .. note::
+ The land-sea mask image cannot be overlaid on top
+ of other images, due to limitations in matplotlib image handling
+ (you can't specify the zorder of an image).
 
- land is colored with rgba integer tuple rgba_land.
- ocean is colored with rgba integer tuple rgba_ocean.
+ ============== ====================================================
+ Arguments Description
+ ============== ====================================================
+ rgba_land rgba integer tuple that describes desired
+ land color. For example, for green (non-transparent)
+ land areas, use rgba_land = (0,255,0,255).
+ rgba_ocean rgba integer tuple that describes desired
+ ocean color. For example, for blue (non-transparent)
+ ocean areas, use (0,0,255,255). To make transparent
+ blue oceans (useful if you just want to mask land
+ regions over another image), use 
+ rgba_ocean = (0,0,255,0).
+ ============== ====================================================
 
- For example, to color oceans blue and land green, use
- rgba_ocean = (0,0,255,255) and rgba_land = (0,255,0,255).
- To make oceans transparent (useful if you just want to mask land
- regions over another image), use rgba_ocean = (0,0,255,0).
+ ============== ====================================================
+ Keywords Description
+ ============== ====================================================
+ lakes If True, inland lakes are also colored with
+ rgba_ocean (default is lakes=False).
+ lsmask An array of 0's for ocean pixels, 1's for
+ land pixels and optionally 2's for inland
+ lake pixels defining a global land-sea mask.
+ Default is None, and default
+ 5-minute resolution land-sea mask is used.
+ lsmask_lons 1d array of longitudes for lsmask (ignored
+ if lsmask is None). Longitudes must be ordered
+ from -180 W eastward.
+ lsmask_lats 1d array of latitudes for lsmask (ignored
+ if lsmask is None). Latitudes must be ordered
+ from -90 S northward.
+ \**kwargs extra keyword arguments passed on to 
+ :meth:`imshow`
+ ============== ====================================================
 
- If lakes=True, inland lakes are also colored with
- rgba_ocean (default is lakes=False).
-
- Default land-sea mask is from
- http://www.ngdc.noaa.gov/ecosys/cdroms/graham/graham/graham.htm
- and has 5-minute resolution.
-
- To specify your own global land-sea mask, set the
- lsmask keyword to a (nlats, nlons) array
- with 0's for ocean pixels, 1's for land pixels and
- optionally 2's for inland lake pixels.
- The lsmask_lons keyword should be a 1-d array
- with the longitudes of the mask, lsmask_lats should be
- a 1-d array with the latitudes. Longitudes should be ordered
- from -180 W eastward, latitudes from -90 S northward.
 If any of the lsmask, lsmask_lons or lsmask_lats keywords are not
- set, the default land-sea mask is used.
+ set, the default land-sea mask from
+ http://www.ngdc.noaa.gov/ecosys/cdroms/graham/graham/graham.htm.
+ is used.
 
- extra keyword 'ax' can be used to override the default axis instance.
+ Extra keyword ``ax`` can be used to override the default axis instance.
 """
 # look for axes instance (as keyword, an instance variable
 # or from plt.gca().
@@ -2898,15 +2928,17 @@
 
 def warpimage(self,image="bluemarble",**kwargs):
 """
- display an image (given by file keyword) as a background.
+ Display an image (given by ``image`` keyword) as a map background.
 
- Default (if file not specified) is to display 
+ Default (if ``image`` not specified) is to display 
 'blue marble next generation' image from http://visibleearth.nasa.gov/.
 
 Specified image must have pixels covering the whole globe in a regular
 lat/lon grid, starting and -180W and the South Pole.
 
- extra keyword 'ax' can be used to override the default axis instance.
+ Extra keyword ``ax`` can be used to override the default axis instance.
+
+ \**kwargs passed on to :meth:`imshow`.
 """
 try:
 from PIL import Image
@@ -2987,36 +3019,36 @@
 units='km',fontsize=9,yoffset=None,labelstyle='simple',\
 fontcolor='k',fillcolor1='w',fillcolor2='k',ax=None):
 """
- draw a map scale at lon,lat representing distance in the map
- projection coordinates at lon0,lat0.
+ Draw a map scale at ``lon,lat`` of length ``length`` 
+ representing distance in the map
+ projection coordinates at ``lon0,lat0``. 
 
- The length of the scale
- is specified by the length argument, with units given by the units
- keyword (default 'km'). 
+ ============== ====================================================
+ Keywords Description
+ ============== ====================================================
+ units the units of the length argument (Default km).
+ barstyle ``simple`` or ``fancy`` (roughly corresponding
+ to the styles provided by Generic Mapping Tools).
+ Default ``simple``. 
+ fontsize for map scale annotations, default 9.
+ color for map scale annotations, default black.
+ labelstype ``simple`` (default) or ``fancy``. For
+ ``fancy`` the map scale factor (ratio betwee
+ the actual distance and map projection distance
+ at lon0,lat0) and the value of lon0,lat0 are also 
+ displayed on the top of the scale bar. For 
+ ``simple``, just the units are display on top
+ and the distance below the scale bar.
+ yoffset yoffset controls how tall the scale bar is,
+ and how far the annotations are offset from the
+ scale bar. Default is 0.02 times the height of 
+ the map (0.02*(self.ymax-self.ymin)).
+ fillcolor1(2) colors of the alternating filled regions
+ (default white and black). Only relevant for 
+ 'fancy' barstyle.
+ ============== ====================================================
 
- Two styles of scale bar are available
- (specified by the labelstyle keyword) - 'simple' and 'fancy', which
- correspond roughly to the corresponding styles provided by 
- the Generic Mapping Tools software. Default is 'simple'.
-
- The fontsize and color of the map scale annotations can be specified
- with the fontsize (default 9) and fontcolor (default black) keywords.
-
- labelstyle='simple' results in basic annotation (the units on top
- of the scalebar and the distance below). This is the default.
- If labelstyle='fancy' the map scale factor (ratio between
- the actual distance and map projection distance at lon0,lat0) and
- the value of lon0,lat0 are also printed on top of the scale bar.
-
- yoffset controls how tall the scale bar is, and how far the annotations
- are offset from the scale bar. Default is 0.02 times the height of the map
- (0.02*(self.ymax-self.ymin)).
-
- fillcolor1 and fillcolor2 are only relevant for the 'fancy' scale bar.
- They are the colors of the alternating filled regions (default white
- and black).
-
- extra keyword 'ax' can be used to override the default axis instance.
+ Extra keyword ``ax`` can be used to override the default axis instance.
 """
 # get current axes instance (if none specified).
 if ax is None and self.ax is None:
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.