Make scatter use the new marker class. Add a "scatter_symbol" example. Make legend support the new kind of scatter.

Author: mdboom

CHANGELOG

@@ -1,3 +1,12 @@
+2001-07-15 The set of markers available in the plot() and scatter()
+           commands has been unified.  In general, this gives more
+           options to both than were previously available, however,
+           there is one backward-incompatible change to the markers in
+           scatter:
+
+              "d" used to mean "diamond", it now means "narrow
+              diamond", now "D" can be used for a "diamond".
+
 2011-07-10 Fixed argument handling error in tripcolor/triplot/tricontour,
            issue #203. - IMT
 

examples/pylab_examples/scatter_symbol.py

@@ -0,0 +1,14 @@
+from matplotlib import pyplot as plt
+import numpy as np
+import matplotlib
+
+x = np.arange(0.0, 50.0, 2.0)
+y = x ** 1.3 + np.random.rand(*x.shape) * 30.0
+s = np.random.rand(*x.shape) * 800 + 500
+
+plt.scatter(x, y, s, c="g", alpha=0.5, marker=r'$\clubsuit$',
+            label="Luck")
+plt.xlabel("Leprechauns")
+plt.ylabel("Gold")
+plt.legend(loc=2)
+plt.show()

lib/matplotlib/axes.py

@@ -22,6 +22,7 @@
 import matplotlib.image as mimage
 import matplotlib.legend as mlegend
 import matplotlib.lines as mlines
+import matplotlib.markers as mmarkers
 import matplotlib.mlab as mlab
 import matplotlib.path as mpath
 import matplotlib.patches as mpatches
@@ -5651,23 +5652,8 @@ def scatter(self, x, y, s=20, c='b', marker='o', cmap=None, norm=None,
           *marker*:
             can be one of:
 
-            =======   ==============
-            Value     Description
-            =======   ==============
-            ``'s'``   square
-            ``'o'``   circle
-            ``'^'``   triangle up
-            ``'>'``   triangle right
-            ``'v'``   triangle down
-            ``'<'``   triangle left
-            ``'d'``   diamond
-            ``'p'``   pentagon
-            ``'h'``   hexagon
-            ``'8'``   octagon
-            ``'+'``   plus
-            ``'x'``   cross
-            =======   ==============
-
+            # TODO: Use documentation in MarkerStyle
+            
             The marker can also be a tuple (*numsides*, *style*,
             *angle*), which will create a custom, regular symbol.
 
@@ -5749,21 +5735,6 @@ def scatter(self, x, y, s=20, c='b', marker='o', cmap=None, norm=None,
 
         if not self._hold: self.cla()
 
-        syms =  { # a dict from symbol to (numsides, angle)
-            's' : (4,math.pi/4.0,0),   # square
-            'o' : (0,0,3),            # circle
-            '^' : (3,0,0),             # triangle up
-            '>' : (3,math.pi/2.0,0),   # triangle right
-            'v' : (3,math.pi,0),       # triangle down
-            '<' : (3,3*math.pi/2.0,0), # triangle left
-            'd' : (4,0,0),             # diamond
-            'p' : (5,0,0),             # pentagon
-            'h' : (6,0,0),             # hexagon
-            '8' : (8,0,0),             # octagon
-            '+' : (4,0,2),             # plus
-            'x' : (4,math.pi/4.0,2)    # cross
-            }
-
         self._process_unit_info(xdata=x, ydata=y, kwargs=kwargs)
         x = self.convert_xunits(x)
         y = self.convert_yunits(y)
@@ -5814,87 +5785,21 @@ def scatter(self, x, y, s=20, c='b', marker='o', cmap=None, norm=None,
             marker = (verts, 0)
             verts = None
 
-        if is_string_like(marker):
-            # the standard way to define symbols using a string character
-            sym = syms.get(marker)
-            if sym is None and verts is None:
-                raise ValueError('Unknown marker symbol to scatter')
-            numsides, rotation, symstyle = syms[marker]
-
-        elif iterable(marker):
-            # accept marker to be:
-            #    (numsides, style, [angle])
-            # or
-            #    (verts[], style, [angle])
-
-            if len(marker)<2 or len(marker)>3:
-                raise ValueError('Cannot create markersymbol from marker')
-
-            if cbook.is_numlike(marker[0]):
-                # (numsides, style, [angle])
-
-                if len(marker)==2:
-                    numsides, rotation = marker[0], 0.
-                elif len(marker)==3:
-                    numsides, rotation = marker[0], marker[2]
-                sym = True
-
-                if marker[1] in (1,2,3):
-                    symstyle = marker[1]
-
-            else:
-                verts = np.asarray(marker[0])
-
-        if sym is not None:
-            if symstyle==0:
-                collection = mcoll.RegularPolyCollection(
-                    numsides, rotation, scales,
-                    facecolors = colors,
-                    edgecolors = edgecolors,
-                    linewidths = linewidths,
-                    offsets = zip(x,y),
-                    transOffset = self.transData,
-                    )
-            elif symstyle==1:
-                collection = mcoll.StarPolygonCollection(
-                    numsides, rotation, scales,
-                    facecolors = colors,
-                    edgecolors = edgecolors,
-                    linewidths = linewidths,
-                    offsets = zip(x,y),
-                    transOffset = self.transData,
-                    )
-            elif symstyle==2:
-                collection = mcoll.AsteriskPolygonCollection(
-                    numsides, rotation, scales,
-                    facecolors = colors,
-                    edgecolors = 'face',
-                    linewidths = linewidths,
-                    offsets = zip(x,y),
-                    transOffset = self.transData,
-                    )
-            elif symstyle==3:
-                collection = mcoll.CircleCollection(
-                    scales,
-                    facecolors = colors,
-                    edgecolors = edgecolors,
-                    linewidths = linewidths,
-                    offsets = zip(x,y),
-                    transOffset = self.transData,
-                    )
-        else:
-            rescale = np.sqrt(max(verts[:,0]**2+verts[:,1]**2))
-            verts /= rescale
-
-            collection = mcoll.PolyCollection(
-                (verts,), scales,
+        marker_obj = mmarkers.MarkerStyle(marker)
+        path = marker_obj.get_path().transformed(
+            marker_obj.get_transform())
+        if not marker_obj.is_filled():
+            edgecolors = 'face'
+        
+        collection = mcoll.PathCollection(
+                (path,), scales,
                 facecolors = colors,
                 edgecolors = edgecolors,
                 linewidths = linewidths,
                 offsets = zip(x,y),
                 transOffset = self.transData,
                 )
-            collection.set_transform(mtransforms.IdentityTransform())
+        collection.set_transform(mtransforms.IdentityTransform())
         collection.set_alpha(alpha)
         collection.update(kwargs)
 

lib/matplotlib/collections.py

@@ -574,7 +574,7 @@ class PathCollection(Collection):
     This is the most basic :class:`Collection` subclass.
     """
     @docstring.dedent_interpd
-    def __init__(self, paths, **kwargs):
+    def __init__(self, paths, sizes=None, **kwargs):
         """
         *paths* is a sequence of :class:`matplotlib.path.Path`
         instances.
@@ -584,11 +584,25 @@ def __init__(self, paths, **kwargs):
 
         Collection.__init__(self, **kwargs)
         self.set_paths(paths)
-
+        self._sizes = sizes
 
     def set_paths(self, paths):
         self._paths = paths
-
+        
+    def get_paths(self):
+        return self._paths
+        
+    def get_sizes(self):
+        return self._sizes
+        
+    @allow_rasterization
+    def draw(self, renderer):
+        if self._sizes is not None:
+            self._transforms = [
+                transforms.Affine2D().scale(
+                    (np.sqrt(x) * self.figure.dpi / 72.0))
+                for x in self._sizes]
+        return Collection.draw(self, renderer)
 
 class PolyCollection(Collection):
     @docstring.dedent_interpd

lib/matplotlib/legend.py

@@ -23,7 +23,7 @@
 from matplotlib.lines import Line2D
 from matplotlib.patches import Patch, Rectangle, Shadow, FancyBboxPatch
 from matplotlib.collections import LineCollection, RegularPolyCollection, \
-     CircleCollection
+     CircleCollection, PathCollection
 from matplotlib.transforms import Bbox, BboxBase, TransformedBbox, BboxTransformTo, BboxTransformFrom
 
 from matplotlib.offsetbox import HPacker, VPacker, TextArea, DrawingArea, DraggableOffsetBox
@@ -481,6 +481,7 @@ def _approx_text_height(self, renderer=None):
         CircleCollection:legend_handler.HandlerCircleCollection(),
         BarContainer:legend_handler.HandlerPatch(update_func=legend_handler.update_from_first_child),
         tuple:legend_handler.HandlerTuple(),
+        PathCollection:legend_handler.HandlerPathCollection()
         }
 
     # (get|set|update)_default_handler_maps are public interfaces to

lib/matplotlib/legend_handler.py

@@ -362,7 +362,19 @@ def create_artists(self, legend, orig_handle,
 
         return [p]
 
+class HandlerPathCollection(HandlerRegularPolyCollection):
+    """
+    Handler for PathCollections, which are used by scatter
+    """
+    def create_collection(self, orig_handle, sizes, offsets, transOffset):
+        p = type(orig_handle)([orig_handle.get_paths()[0]],
+                              sizes=sizes,
+                              offsets=offsets,
+                              transOffset=transOffset,
+                              )
+        return p
 
+    
 class HandlerCircleCollection(HandlerRegularPolyCollection):
     """
     Handler for CircleCollections

lib/matplotlib/lines.py

@@ -103,6 +103,12 @@ class Line2D(Artist):
     # Need a list ordered with long names first:
     drawStyleKeys = _drawStyles_l.keys() + _drawStyles_s.keys()
 
+    # Referenced here to maintain API.  These are defined in
+    # MarkerStyle
+    markers = MarkerStyle.markers
+    filled_markers = MarkerStyle.filled_markers
+    fillStyles = MarkerStyle.fillstyles
+    
     zorder = 2
     validCap = ('butt', 'round', 'projecting')
     validJoin =   ('miter', 'round', 'bevel')