DOCS: @timhoffm collections.py suggestions

brunobeltran · brunobeltran · commit e98db08c4452 · 2020-06-05T12:31:36.000-07:00
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -27,34 +27,36 @@
     "linewidth": ["linewidths", "lw"],
 })
 class Collection(artist.Artist, cm.ScalarMappable):
-    """
+    r"""
     Base class for Collections. Must be subclassed to be usable.
 
-    A Collection represents a sequence of `~.patches.Patch` objects that the
-    library believes would be more efficient to draw together than
-    individually. For example, when a single path is being drawn repeatedly at
-    different offsets, the renderer can typically execute a `draw_marker` call
-    much more efficiently than a series of repeated calls to `draw_path` with
-    the offsets put in one-by-one.
+    A Collection represents a sequence of `~.patches.Patch`\s that can be drawn
+    more efficiently together than individually. For example, when a single
+    path is being drawn repeatedly at different offsets, the renderer can
+    typically execute a ``draw_marker()`` call much more efficiently than a
+    series of repeated calls to ``draw_path()`` with the offsets put in
+    one-by-one.
+
+    Most properties of a collection can be configured per-element. Therefore,
+    Collections have "plural" versions of many of the properties of a
+    `~.patches.Patch` (e.g. `.Collection.get_paths` instead of
+    `~.patches.Patch.get_path`). Exceptions are the *zorder*, *hatch*,
+    *pickradius*, *capstyle* and *joinstyle* properties, which can only be set
+    globally for the whole collection.
 
-    All properties in a collection can be either sequences or scalars; if
-    scalars, they will be converted to sequences. The property of the ith
-    element of the collection is::
+    Besides these exceptions, all properties can be specified as single values
+    (applying to all elements) or sequences of values. The property of the
+    ``i``th element of the collection is::
 
-      prop[i % len(props)]
+      prop[i % len(prop)]
 
-    Because of this, Collections have "plural" versions of many of the
-    properties of a `~.patches.Patch` (e.g. `Collection.get_paths` instead of
-    `~.patches.Patch.get_path`). Exceptions are the *hatch*, *pickradius*,
-    *capstyle* and *joinstyle* properties, these can only be set globally for
-    the whole collection.
 
     Each Collection can optionally be used as its own `~.cm.ScalarMappable` by
     passing the *norm* and *cmap* parameters to its constructor. If the
     Collection's `~.cm.ScalarMappable` matrix ``_A`` has been set (via a call
-    to `Collection.set_array`), then at draw time this internal scalar mappable
-    will be used to set the ``facecolors`` and ``edgecolors``, ignoring those
-    that were manually passed in.
+    to `.Collection.set_array`), then at draw time this internal scalar
+    mappable will be used to set the ``facecolors`` and ``edgecolors``,
+    ignoring those that were manually passed in.
     """
     _offsets = np.zeros((0, 2))
     _transOffset = transforms.IdentityTransform()
@@ -91,13 +93,19 @@ def __init__(self,
                  **kwargs
                  ):
         """
+        For all "plural" parameters, the type listed is the expected type when
+        passing a single value to be used for the whole collection. For any of
+        these inputs, a Sequence of the specified type is also allowed.
+
         Parameters
         ----------
-        edgecolors : default: :rc:`patch.edgecolor`
-            Edge color for each patch making up the collection.
-        facecolors : default: :rc:`patch.facecolor`
+        edgecolors : color, default: :rc:`patch.edgecolor`
+            Edge color for each patch making up the collection. The special
+            value 'face' can be passed to make the edgecolor match the
+            facecolor.
+        facecolors : color, default: :rc:`patch.facecolor`
             Face color for each patch making up the collection.
-        linewidths : default: :rc:`patch.linewidth`
+        linewidths : float, default: :rc:`patch.linewidth`
             Line width for each patch making up the collection.
         linestyles : str or tuple, default: 'solid'
             Valid strings are ['solid', 'dashed', 'dashdot', 'dotted', '-',
@@ -108,14 +116,14 @@ def __init__(self,
             where *onoffseq* is an even length tuple of on and off ink lengths
             in points. For examples, see
             :doc:`/gallery/lines_bars_and_markers/linestyles`.
-        capstyle : default: :rc:`patch.capstyle`
+        capstyle : str, default: :rc:`patch.capstyle`
             Style to use for capping lines for all paths in the collection.
-        joinstyle : default: :rc:`patch.joinstyle`
+        joinstyle : str, default: :rc:`patch.joinstyle`
             Style to use for joining lines for all paths in the collection.
-        antialiaseds : default: :rc:`patch.antialiased`
+        antialiaseds : bool, default: :rc:`patch.antialiased`
             Whether each pach in the collection should be drawn with
             antialiasing.
-        offsets : Tuple[float, float], default: (0, 0)
+        offsets : (float, float), default: (0, 0)
             A vector by which to translate each patch after rendering (default
             is no translation). The translation is performed in screen (pixel)
             coordinates (i.e. after the Artist's transform is applied).
@@ -126,25 +134,25 @@ def __init__(self,
             If set to 'data' (deprecated), *offsets* will be treated as if it
             is in data coordinates instead of in screen coordinates.
         norm : `~.colors.Normalize`, optional, default: None
-            Forwarded to `~.cm.ScalarMappable.__init__`. The default of
+            Forwarded to `~.cm.ScalarMappable`. The default of
             ``None`` means that the first draw call will set ``vmin`` and
             ``vmax`` using the minimum and maximum values of the data.
         cmap : `~.colors.Colormap`, optional, default: None
-            Forwarded to `~.cm.ScalarMappable.__init__`. The default of
+            Forwarded to `~.cm.ScalarMappable`. The default of
             ``None`` will result in :rc:`image.cmap` being used.
-        hatch : Optional[str], default: None
+        hatch : str, optional, default: None
             Hatching pattern to use in filled paths, if any.  Valid strings are
             ['/', '\\', '|', '-', '+', 'x', 'o', 'O', '.', '*']. See
             :doc:`/gallery/shapes_and_collections/hatch_demo` for the meaning
             of each hatch type.
-        pickradius : float, default: 5
-            If ``pickradius <= 0``, then `Collection.contains` will return
+        pickradius : float, default: 5.0
+            If ``pickradius <= 0``, then `.Collection.contains` will return
             ``True`` whenever the test point is inside of one of the polygons
             formed by the control points of a Path in the Collection. On the
             other hand, if it is greater than 0, then we instead check if the
             test point is contained in a stroke of width ``2*pickradius``
             following any of the Paths in the Collection.
-        urls : str or Sequence[str], default: None
+        urls : str, default: None
             A URL for each patch to link to once drawn. Currently only works
             for the SVG backend. See :doc:`/gallery/misc/hyperlinks_sgskip` for
             examples.
@@ -223,24 +231,21 @@ def get_offset_transform(self):
         return t
 
     def get_datalim(self, transData):
-        """
-        Get the automatic datalim of the collection.
-
-        This operation depends on the transforms for the data in the
-        collection and whether the collection has offsets.
-
-        1. offsets = None, transform child of transData: use the paths for
-        the automatic limits (i.e. for LineCollection in streamline).
-        2. offsets != None: offset_transform is child of transData:
-
-           a. transform is child of transData: use the path + offset for
-              limits (i.e for bar).
-           b. transform is not a child of transData: just use the offsets
-              for the limits (i.e. for scatter)
-
-        3. otherwise return a null Bbox.
-
-        """
+        # Calculate the data limits and return them as a `.Bbox`.
+        #
+        # This operation depends on the transforms for the data in the
+        # collection and whether the collection has offsets:
+        #
+        # 1. offsets = None, transform child of transData: use the paths for
+        # the automatic limits (i.e. for LineCollection in streamline).
+        # 2. offsets != None: offset_transform is child of transData:
+        #
+        #    a. transform is child of transData: use the path + offset for
+        #       limits (i.e for bar).
+        #    b. transform is not a child of transData: just use the offsets
+        #       for the limits (i.e. for scatter)
+        #
+        # 3. otherwise return a null Bbox.
 
         transform = self.get_transform()
         transOffset = self.get_offset_transform()
@@ -439,10 +444,11 @@ def contains(self, mouseevent):
         if not self.get_visible():
             return False, {}
 
-        if isinstance(self._picker, Number) and self._picker is not True:
-            pickradius = float(self._picker)  # Artist._picker not just a bool
-        else:
-            pickradius = self._pickradius
+        pickradius = (
+            float(self._picker)
+            if isinstance(self._picker, Number) and
+               self._picker is not True  # the bool, not just nonzero or 1
+            else self._pickradius)
 
         if self.axes:
             self.axes._unstale_viewLim()
@@ -466,21 +472,22 @@ def set_urls(self, urls):
         """
         Parameters
         ----------
-        urls : List[str] or None
+        urls : list of str or None
 
         Notes
         -----
-        Currently only works for the SVG backend.
+        URLs are currently only implemented by the SVG backend. They are
+        ignored by all other backends.
         """
         self._urls = urls if urls is not None else [None]
         self.stale = True
 
     def get_urls(self):
         """
-        Returns
-        -------
-        The URL that each patch should link to once drawn. See
-        :doc:`/gallery/misc/hyperlinks_sgskip` for a examples.
+        Return a list of URLs, one for each element of the collection.
+
+        The list contains *None* for elements without a URL. See
+        :doc:`/gallery/misc/hyperlinks_sgskip` for an example.
         """
         return self._urls
 
@@ -925,21 +932,21 @@ def draw(self, renderer):
 
 class PathCollection(_CollectionWithSizes):
     """
-    The most basic `Collection` subclass, created e.g. by `~.Axes.scatter`.
+    The most basic `.Collection` subclass, created e.g. by `~.Axes.scatter`.
     """
 
     def __init__(self, paths, sizes=None, **kwargs):
         """
         Parameters
         ----------
-        paths : Sequence[matplotlib.path.Path]
-            The paths that will make up the `Collection`.
-        sizes : Sequence[float]
-            Scalar by which to scale each drawn `~.path.Path`. One unit squared
-            in the Path's data space is scaled to be ``sizes**2`` points when
-            rendered.
+        paths : list of matplotlib.path.Path
+            The paths that will make up the `.Collection`.
+        sizes : array-like of float
+            The factor by which to scale each drawn `~.path.Path`. One unit
+            squared in the Path's data space is scaled to be ``sizes**2``
+            points when rendered.
         **kwargs
-            Forwarded to `Collection`.
+            Forwarded to `.Collection`.
         """
 
         super().__init__(**kwargs)
@@ -959,17 +966,17 @@ def legend_elements(self, prop="colors", num="auto",
         """
         Create legend handles and labels for a PathCollection.
 
-        Each legend handle is just a `.Line2D` representing the Path that was
-        drawn, and each label is just a string what each Path represents.
+        Each legend handle is a `.Line2D` representing the Path that was drawn,
+        and each label is a string what each Path represents.
 
         This is useful for obtaining a legend for a `~.Axes.scatter` plot;
         e.g.::
 
             scatter = plt.scatter([1, 2, 3],  [4, 5, 6],  c=[7, 2, 3])
             plt.legend(*scatter.legend_elements())
 
-        would create three legend elements, one for each color with the
-        numerical values passed to *c* as the labels.
+        creates three legend elements, one for each color with the numerical
+        values passed to *c* as the labels.
 
         Also see the :ref:`automatedlegendcreation` example.
 
@@ -1109,7 +1116,7 @@ def __init__(self, verts, sizes=None, closed=True, **kwargs):
             Whether the polygon should be closed by adding a CLOSEPOLY
             connection at the end.
         **kwargs
-            Forwarded to `Collection`.
+            Forwarded to `.Collection`.
         """
         Collection.__init__(self, **kwargs)
         self.set_sizes(sizes)
@@ -1192,7 +1199,7 @@ def __init__(self, xranges, yrange, **kwargs):
         yrange : (float, float)
             The (lower-edge, height) common to all bars.
         **kwargs
-            Forwarded to `Collection`.
+            Forwarded to `.Collection`.
         """
         ymin, ywidth = yrange
         ymax = ymin + ywidth
@@ -1206,7 +1213,7 @@ def __init__(self, xranges, yrange, **kwargs):
     @classmethod
     def span_where(cls, x, ymin, ymax, where, **kwargs):
         """
-        Return a `BrokenBarHCollection` that plots horizontal bars from
+        Return a `.BrokenBarHCollection` that plots horizontal bars from
         over the regions in *x* where *where* is True.  The bars range
         on the y-axis from *ymin* to *ymax*
 
@@ -1242,7 +1249,7 @@ def __init__(self,
         sizes : tuple of float
             The area of the circle circumscribing the polygon in points^2.
         **kwargs
-            Forwarded to `Collection`.
+            Forwarded to `.Collection`.
 
         Examples
         --------
@@ -1296,7 +1303,7 @@ class AsteriskPolygonCollection(RegularPolyCollection):
 
 class LineCollection(Collection):
     """
-    A collection of 2D lines, where each line can be many segments long.
+    Collection of 2D lines. Each line may have an arbitrary number of segments.
 
     Relevant parameters default to their ``'lines'`` values in
     `~.matplotlib.rcParams` instead of their ``'patch'`` values.
@@ -1319,6 +1326,13 @@ def __init__(self, segments,     # Can be None.
                  **kwargs
                  ):
         """
+        Except for *segments*, the type listed below is the expected type when
+        passing a single value to be used for the whole collection. A Sequence
+        of the specified type is also allowed, in which case the property for
+        the ``i``th element of the collection will be::
+
+            prop[i % len(prop)]
+
         Parameters
         ----------
         segments
@@ -1328,9 +1342,9 @@ def __init__(self, segments,     # Can be None.
 
             or the equivalent numpy array with two columns. Each line
             can have a different number of segments.
-        linewidths : default: :rc:`lines.linewidth`
+        linewidths : float, default: :rc:`lines.linewidth`
             The width of each line in points.
-        colors : default: :rc:`lines.color`
+        colors : color, default: :rc:`lines.color`
             A sequence of RGBA tuples (e.g., arbitrary color strings, etc, not
             allowed).
         antialiaseds : default: :rc:`lines.antialiased`
@@ -1343,10 +1357,11 @@ def __init__(self, segments,     # Can be None.
            "filled in" as if there was an implicit line segment joining the
            last and first points of that line back around to each other. In
            order to manually specify what should count as the "interior" of
-           each line, please use `PathCollection` instead, where the "interior"
-           can be specified by appropriate usage of `~.path.Path.CLOSEPOLY`.
+           each line, please use `.PathCollection` instead, where the
+           "interior" can be specified by appropriate usage of
+           `~.path.Path.CLOSEPOLY`.
         **kwargs
-            Forwareded to `Collection`.
+            Forwareded to `.Collection`.
         """
         if colors is None:
             colors = mpl.rcParams['lines.color']
@@ -1492,7 +1507,7 @@ def __init__(self,
         antialiased : bool, default: :rc:`lines.antialiased`
             Whether to use antialiasing for drawing the lines.
         **kwargs
-            Forwarded to :class:`~matplotlib.collections.LineCollection`.
+            Forwarded to `.LineCollection`.
 
         Examples
         --------
@@ -1650,10 +1665,10 @@ def __init__(self, sizes, **kwargs):
         """
         Parameters
         ----------
-        sizes : float or Sequence[float]
+        sizes : float or array-like
             Gives the area of each circle in points^2.
         **kwargs
-            Forwarded to `Collection`.
+            Forwarded to `.Collection`.
         """
         Collection.__init__(self, **kwargs)
         self.set_sizes(sizes)
@@ -1687,7 +1702,7 @@ def __init__(self, widths, heights, angles, units='points', **kwargs):
             it behaves the same as the `~matplotlib.patches.Ellipse` with
             ``axes.transData`` as its transform.
         **kwargs
-            Forwarded to :class:`Collection`.
+            Forwarded to `Collection`.
         """
         Collection.__init__(self, **kwargs)
         self._widths = 0.5 * np.asarray(widths).ravel()
