Cleanup collections docs.

anntzer · anntzer · commit 7d83aa076312 · 2018-11-20T23:04:16.000+01:00
diff --git a/doc/api/next_api_changes/2018-11-20-AL-removals.rst b/doc/api/next_api_changes/2018-11-20-AL-removals.rst
@@ -0,0 +1,4 @@
+Removals
+````````
+
+The ``collections.CIRCLE_AREA_FACTOR`` constant has been removed.
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -17,8 +17,6 @@
 from . import (_path, artist, cbook, cm, colors as mcolors, docstring,
                lines as mlines, path as mpath, transforms)
 
-CIRCLE_AREA_FACTOR = 1.0 / np.sqrt(np.pi)
-
 
 @cbook._define_aliases({
     "antialiased": ["antialiaseds"],
@@ -58,7 +56,6 @@ class Collection(artist.Artist, cm.ScalarMappable):
         * *hatch*: None
         * *zorder*: 1
 
-
     *offsets* and *transOffset* are used to translate the patch after
     rendering (default no offsets).  If offset_position is 'screen'
     (default) the offset is applied after the master transform has
@@ -207,12 +204,12 @@ def get_datalim(self, transData):
         return result
 
     def get_window_extent(self, renderer):
-        # TODO:check to ensure that this does not fail for
+        # TODO: check to ensure that this does not fail for
         # cases other than scatter plot legend
         return self.get_datalim(transforms.IdentityTransform())
 
     def _prepare_points(self):
-        """Point prep for drawing and hit testing"""
+        # Helper for drawing and hit testing.
 
         transform = self.get_transform()
         transOffset = self.get_offset_transform()
@@ -227,8 +224,7 @@ def _prepare_points(self):
                 xs = self.convert_xunits(xs)
                 ys = self.convert_yunits(ys)
                 paths.append(mpath.Path(np.column_stack([xs, ys]), path.codes))
-
-            if offsets.size > 0:
+            if offsets.size:
                 xs = self.convert_xunits(offsets[:, 0])
                 ys = self.convert_yunits(offsets[:, 1])
                 offsets = np.column_stack([xs, ys])
@@ -336,7 +332,8 @@ def draw(self, renderer):
         self.stale = False
 
     def set_pickradius(self, pr):
-        """Set the pick radius used for containment tests.
+        """
+        Set the pick radius used for containment tests.
 
         Parameters
         ----------
@@ -352,8 +349,8 @@ def contains(self, mouseevent):
         """
         Test whether the mouse event occurred in the collection.
 
-        Returns True | False, ``dict(ind=itemlist)``, where every
-        item in itemlist contains the event.
+        Returns ``bool, dict(ind=itemlist)``, where every item in itemlist
+        contains the event.
         """
         if callable(self._contains):
             return self._contains(self, mouseevent)
@@ -430,8 +427,7 @@ def get_hatch(self):
 
     def set_offsets(self, offsets):
         """
-        Set the offsets for the collection.  *offsets* can be a scalar
-        or a sequence.
+        Set the offsets for the collection.
 
         Parameters
         ----------
@@ -552,8 +548,7 @@ def set_linestyle(self, ls):
 
     def set_capstyle(self, cs):
         """
-        Set the capstyle for the collection. The capstyle can
-        only be set globally for all elements in the collection
+        Set the capstyle for the collection (for all its elements).
 
         Parameters
         ----------
@@ -570,8 +565,7 @@ def get_capstyle(self):
 
     def set_joinstyle(self, js):
         """
-        Set the joinstyle for the collection. The joinstyle can only be
-        set globally for all elements in the collection.
+        Set the joinstyle for the collection (for all its elements).
 
         Parameters
         ----------
@@ -588,28 +582,26 @@ def get_joinstyle(self):
 
     @staticmethod
     def _bcast_lwls(linewidths, dashes):
-        '''Internal helper function to broadcast + scale ls/lw
+        """
+        Internal helper function to broadcast + scale ls/lw
 
-        In the collection drawing code the linewidth and linestyle are
-        cycled through as circular buffers (via v[i % len(v)]).  Thus,
-        if we are going to scale the dash pattern at set time (not
-        draw time) we need to do the broadcasting now and expand both
-        lists to be the same length.
+        In the collection drawing code, the linewidth and linestyle are cycled
+        through as circular buffers (via ``v[i % len(v)]``).  Thus, if we are
+        going to scale the dash pattern at set time (not draw time) we need to
+        do the broadcasting now and expand both lists to be the same length.
 
         Parameters
         ----------
         linewidths : list
             line widths of collection
-
         dashes : list
             dash specification (offset, (dash pattern tuple))
 
         Returns
         -------
         linewidths, dashes : list
              Will be the same length, dashes are scaled by paired linewidth
-
-        '''
+        """
         if mpl.rcParams['_internal.classic_mode']:
             return linewidths, dashes
         # make sure they are the same length so we can zip them
@@ -723,26 +715,20 @@ def _set_edgecolor(self, c):
 
     def set_edgecolor(self, c):
         """
-        Set the edgecolor(s) of the collection. *c* can be a
-        matplotlib color spec (all patches have same color), or a
-        sequence of specs; if it is a sequence the patches will
-        cycle through the sequence.
-
-        If *c* is 'face', the edge color will always be the same as
-        the face color.  If it is 'none', the patch boundary will not
-        be drawn.
+        Set the edgecolor(s) of the collection.
 
         Parameters
         ----------
-        c : color or sequence of colors
+        c : color or sequence of colors or 'face'
+            The collection edgecolor(s).  If a sequence, the patches cycle
+            through it.  If 'face', match the facecolor.
         """
         self._original_edgecolor = c
         self._set_edgecolor(c)
 
     def set_alpha(self, alpha):
         """
-        Set the alpha tranparencies of the collection.  *alpha* must be
-        a float or *None*.
+        Set the alpha tranparencies of the collection.
 
         Parameters
         ----------
@@ -765,10 +751,7 @@ def get_linestyle(self):
         return self._linestyles
 
     def update_scalarmappable(self):
-        """
-        If the scalar mappable array is not none, update colors
-        from scalar data
-        """
+        """Update colors from the scalar mappable array, if it is not None."""
         if self._A is None:
             return
         if self._A.ndim > 1:
@@ -861,7 +844,6 @@ def set_sizes(self, sizes, dpi=72.0):
         sizes : ndarray or None
             The size to set for each element of the collection.  The
             value is the 'area' of the element.
-
         dpi : float
             The dpi of the canvas. Defaults to 72.0.
         """
@@ -963,7 +945,7 @@ def set_verts(self, verts, closed=True):
     set_paths = set_verts
 
     def set_verts_and_codes(self, verts, codes):
-        '''This allows one to initialize vertices with path codes.'''
+        """This allows one to initialize vertices with path codes."""
         if len(verts) != len(codes):
             raise ValueError("'codes' must be a 1D list or array "
                              "with the same length of 'verts'")
@@ -1025,9 +1007,9 @@ def span_where(x, ymin, ymax, where, **kwargs):
 
 class RegularPolyCollection(_CollectionWithSizes):
     """Draw a collection of regular polygons with *numsides*."""
-    _path_generator = mpath.Path.unit_regular_polygon
 
-    _factor = CIRCLE_AREA_FACTOR
+    _path_generator = mpath.Path.unit_regular_polygon
+    _factor = np.pi ** (-1/2)
 
     @docstring.dedent_interpd
     def __init__(self,
@@ -1089,16 +1071,12 @@ def draw(self, renderer):
 
 
 class StarPolygonCollection(RegularPolyCollection):
-    """
-    Draw a collection of regular stars with *numsides* points."""
-
+    """Draw a collection of regular stars with *numsides* points."""
     _path_generator = mpath.Path.unit_regular_star
 
 
 class AsteriskPolygonCollection(RegularPolyCollection):
-    """
-    Draw a collection of regular asterisks with *numsides* points."""
-
+    """Draw a collection of regular asterisks with *numsides* points."""
     _path_generator = mpath.Path.unit_regular_asterisk
 
 
@@ -1295,13 +1273,13 @@ def get_color(self):
 
 
 class EventCollection(LineCollection):
-    '''
+    """
     A collection of discrete events.
 
     The events are given by a 1-dimensional array, usually the position of
     something along an axis, such as time or length.  They do not have an
     amplitude and are displayed as vertical or horizontal parallel bars.
-    '''
+    """
 
     _edge_default = True
 
@@ -1542,10 +1520,9 @@ def get_color(self):
 
 
 class CircleCollection(_CollectionWithSizes):
-    """
-    A collection of circles, drawn using splines.
-    """
-    _factor = CIRCLE_AREA_FACTOR
+    """A collection of circles, drawn using splines."""
+
+    _factor = np.pi ** (-1/2)
 
     @docstring.dedent_interpd
     def __init__(self, sizes, **kwargs):
@@ -1562,9 +1539,8 @@ def __init__(self, sizes, **kwargs):
 
 
 class EllipseCollection(Collection):
-    """
-    A collection of ellipses, drawn using splines.
-    """
+    """A collection of ellipses, drawn using splines."""
+
     @docstring.dedent_interpd
     def __init__(self, widths, heights, angles, units='points', **kwargs):
         """
@@ -1607,9 +1583,8 @@ def __init__(self, widths, heights, angles, units='points', **kwargs):
         self._paths = [mpath.Path.unit_circle()]
 
     def _set_transforms(self):
-        """
-        Calculate transforms immediately before drawing.
-        """
+        """Calculate transforms immediately before drawing."""
+
         ax = self.axes
         fig = self.figure
 
@@ -1712,11 +1687,9 @@ def set_paths(self, patches):
 
 class TriMesh(Collection):
     """
-    Class for the efficient drawing of a triangular mesh using
-    Gouraud shading.
+    Class for the efficient drawing of a triangular mesh using Gouraud shading.
 
-    A triangular mesh is a :class:`~matplotlib.tri.Triangulation`
-    object.
+    A triangular mesh is a `~matplotlib.tri.Triangulation` object.
     """
     def __init__(self, triangulation, **kwargs):
         Collection.__init__(self, **kwargs)
@@ -1743,11 +1716,10 @@ def set_paths(self):
     @staticmethod
     def convert_mesh_to_paths(tri):
         """
-        Converts a given mesh into a sequence of
-        :class:`matplotlib.path.Path` objects for easier rendering by
-        backends that do not directly support meshes.
+        Converts a given mesh into a sequence of `~.Path` objects.
 
-        This function is primarily of use to backend implementers.
+        This function is primarily of use to implementers of backends that do
+        not directly support meshes.
         """
         triangles = tri.get_masked_triangles()
         verts = np.stack((tri.x[triangles], tri.y[triangles]), axis=-1)
@@ -1839,11 +1811,10 @@ def get_datalim(self, transData):
     @staticmethod
     def convert_mesh_to_paths(meshWidth, meshHeight, coordinates):
         """
-        Converts a given mesh into a sequence of
-        :class:`matplotlib.path.Path` objects for easier rendering by
-        backends that do not directly support quadmeshes.
+        Converts a given mesh into a sequence of `~.Path` objects.
 
-        This function is primarily of use to backend implementers.
+        This function is primarily of use to implementers of backends that do
+        not directly support quadmeshes.
         """
         if isinstance(coordinates, np.ma.MaskedArray):
             c = coordinates.data
@@ -1863,7 +1834,7 @@ def convert_mesh_to_triangles(self, meshWidth, meshHeight, coordinates):
         """
         Converts a given mesh into a sequence of triangles, each point
         with its own color.  This is useful for experiments using
-        `draw_qouraud_triangle`.
+        `draw_gouraud_triangle`.
         """
         if isinstance(coordinates, np.ma.MaskedArray):
             p = coordinates.data
