Merge pull request #14256 from timhoffm/doc-barbs

tacaswell · web-flow · commit 476e0c211d17 · 2019-06-09T23:47:23.000-04:00
DOC: Improve docstring of Axes.barbs
diff --git a/lib/matplotlib/quiver.py b/lib/matplotlib/quiver.py
@@ -779,142 +779,141 @@ def _h_arrows(self, length):
 
 
 _barbs_doc = r"""
-Plot a 2-D field of barbs.
+Plot a 2D field of barbs.
 
-Call signatures::
+Call signature::
+
+  barbs([X, Y], U, V, [C], **kw)
+
+Where *X*, *Y* define the barb locations, *U*, *V* define the barb
+directions, and *C* optionally sets the color.
 
-  barb(U, V, **kw)
-  barb(U, V, C, **kw)
-  barb(X, Y, U, V, **kw)
-  barb(X, Y, U, V, C, **kw)
+All arguments may be 1D or 2D. *U*, *V*, *C* may be masked arrays, but masked
+*X*, *Y* are not supported at present.
 
-Arguments:
+Barbs are traditionally used in meteorology as a way to plot the speed
+and direction of wind observations, but can technically be used to
+plot any two dimensional vector quantity.  As opposed to arrows, which
+give vector magnitude by the length of the arrow, the barbs give more
+quantitative information about the vector magnitude by putting slanted
+lines or a triangle for various increments in magnitude, as show
+schematically below::
 
-  *X*, *Y*:
-    The x and y coordinates of the barb locations
-    (default is head of barb; see *pivot* kwarg)
+  :                   /\    \
+  :                  /  \    \
+  :                 /    \    \    \
+  :                /      \    \    \
+  :               ------------------------------
 
-  *U*, *V*:
-    Give the x and y components of the barb shaft
 
-  *C*:
-    An optional array used to map colors to the barbs
+The largest increment is given by a triangle (or "flag"). After those
+come full lines (barbs). The smallest increment is a half line.  There
+is only, of course, ever at most 1 half line.  If the magnitude is
+small and only needs a single half-line and no full lines or
+triangles, the half-line is offset from the end of the barb so that it
+can be easily distinguished from barbs with a single full line.  The
+magnitude for the barb shown above would nominally be 65, using the
+standard increments of 50, 10, and 5.
+
+See also https://en.wikipedia.org/wiki/Wind_barb.
+
+
+
+Parameters
+----------
+X, Y : 1D or 2D array-like, optional
+    The x and y coordinates of the barb locations. See *pivot* for how the
+    barbs are drawn to the x, y positions.
+
+    If not given, they will be generated as a uniform integer meshgrid based
+    on the dimensions of *U* and *V*.
+
+    If *X* and *Y* are 1D but *U*, *V* are 2D, *X*, *Y* are expanded to 2D
+    using ``X, Y = np.meshgrid(X, Y)``. In this case ``len(X)`` and ``len(Y)``
+    must match the column and row dimensions of *U* and *V*.
 
-All arguments may be 1-D or 2-D arrays or sequences. If *X* and *Y*
-are absent, they will be generated as a uniform grid.  If *U* and *V*
-are 2-D arrays but *X* and *Y* are 1-D, and if ``len(X)`` and ``len(Y)``
-match the column and row dimensions of *U*, then *X* and *Y* will be
-expanded with :func:`numpy.meshgrid`.
+U, V : 1D or 2D array-like
+    The x and y components of the barb shaft.
 
-*U*, *V*, *C* may be masked arrays, but masked *X*, *Y* are not
-supported at present.
+C : 1D or 2D array-like, optional
+    Numeric data that defines the barb colors by colormapping via *norm* and
+    *cmap*.
 
-Keyword arguments:
+    This does not support explicit colors. If you want to set colors directly,
+    use *barbcolor* instead.
 
-  *length*:
+length : float, default: 7
     Length of the barb in points; the other parts of the barb
     are scaled against this.
-    Default is 7.
 
-  *pivot*: [ 'tip' | 'middle' | float ]
-    The part of the arrow that is at the grid point; the arrow rotates
-    about this point, hence the name *pivot*.  Default is 'tip'. Can
-    also be a number, which shifts the start of the barb that many
-    points from the origin.
+pivot : {'tip', 'middle'} or float, default: 'tip'
+    The part of the arrow that is anchored to the *X*, *Y* grid. The barb
+    rotates about this point. This can also be a number, which shifts the
+    start of the barb that many points away from grid point.
 
-  *barbcolor*: [ color | color sequence ]
-    Specifies the color all parts of the barb except any flags.  This
+barbcolor : color or color sequence
+    Specifies the color of all parts of the barb except for the flags.  This
     parameter is analogous to the *edgecolor* parameter for polygons,
     which can be used instead. However this parameter will override
     facecolor.
 
-  *flagcolor*: [ color | color sequence ]
+flagcolor : color or color sequence
     Specifies the color of any flags on the barb.  This parameter is
     analogous to the *facecolor* parameter for polygons, which can be
-    used instead. However this parameter will override facecolor.  If
+    used instead. However, this parameter will override facecolor.  If
     this is not set (and *C* has not either) then *flagcolor* will be
     set to match *barbcolor* so that the barb has a uniform color. If
     *C* has been set, *flagcolor* has no effect.
 
-  *sizes*:
+sizes : dict, optional
     A dictionary of coefficients specifying the ratio of a given
     feature to the length of the barb. Only those values one wishes to
     override need to be included.  These features include:
 
-        - 'spacing' - space between features (flags, full/half barbs)
-
-        - 'height' - height (distance from shaft to top) of a flag or
-          full barb
-
-        - 'width' - width of a flag, twice the width of a full barb
+    - 'spacing' - space between features (flags, full/half barbs)
+    - 'height' - height (distance from shaft to top) of a flag or full barb
+    - 'width' - width of a flag, twice the width of a full barb
+    - 'emptybarb' - radius of the circle used for low magnitudes
 
-        - 'emptybarb' - radius of the circle used for low magnitudes
+fill_empty : bool, default: False
+    Whether the empty barbs (circles) that are drawn should be filled with
+    the flag color.  If they are not filled, the center is transparent.
 
-  *fill_empty*:
-    A flag on whether the empty barbs (circles) that are drawn should
-    be filled with the flag color.  If they are not filled, they will
-    be drawn such that no color is applied to the center.  Default is
-    False
+rounding : bool, default: True
+    Whether the vector magnitude should be rounded when allocating barb
+    components.  If True, the magnitude is rounded to the nearest multiple
+    of the half-barb increment.  If False, the magnitude is simply truncated
+    to the next lowest multiple.
 
-  *rounding*:
-    A flag to indicate whether the vector magnitude should be rounded
-    when allocating barb components.  If True, the magnitude is
-    rounded to the nearest multiple of the half-barb increment.  If
-    False, the magnitude is simply truncated to the next lowest
-    multiple.  Default is True
-
-  *barb_increments*:
+barb_increments : dict, optional
     A dictionary of increments specifying values to associate with
     different parts of the barb. Only those values one wishes to
     override need to be included.
 
-        - 'half' - half barbs (Default is 5)
+    - 'half' - half barbs (Default is 5)
+    - 'full' - full barbs (Default is 10)
+    - 'flag' - flags (default is 50)
 
-        - 'full' - full barbs (Default is 10)
+flip_barb : bool or array-like of bool, default: False
+    Whether the lines and flags should point opposite to normal.
+    Normal behavior is for the barbs and lines to point right (comes from wind
+    barbs having these features point towards low pressure in the Northern
+    Hemisphere).
 
-        - 'flag' - flags (default is 50)
+    A single value is applied to all barbs. Individual barbs can be flipped by
+    passing a bool array of the same size as *U* and *V*.
 
-  *flip_barb*:
-    Either a single boolean flag or an array of booleans.  Single
-    boolean indicates whether the lines and flags should point
-    opposite to normal for all barbs.  An array (which should be the
-    same size as the other data arrays) indicates whether to flip for
-    each individual barb.  Normal behavior is for the barbs and lines
-    to point right (comes from wind barbs having these features point
-    towards low pressure in the Northern Hemisphere.)  Default is
-    False
+Returns
+-------
+barbs : `~matplotlib.quiver.Barbs`
 
-Barbs are traditionally used in meteorology as a way to plot the speed
-and direction of wind observations, but can technically be used to
-plot any two dimensional vector quantity.  As opposed to arrows, which
-give vector magnitude by the length of the arrow, the barbs give more
-quantitative information about the vector magnitude by putting slanted
-lines or a triangle for various increments in magnitude, as show
-schematically below::
-
- :     /\    \\
- :    /  \    \\
- :   /    \    \    \\
- :  /      \    \    \\
- : ------------------------------
-
-.. note the double \\ at the end of each line to make the figure
-.. render correctly
-
-The largest increment is given by a triangle (or "flag"). After those
-come full lines (barbs). The smallest increment is a half line.  There
-is only, of course, ever at most 1 half line.  If the magnitude is
-small and only needs a single half-line and no full lines or
-triangles, the half-line is offset from the end of the barb so that it
-can be easily distinguished from barbs with a single full line.  The
-magnitude for the barb shown above would nominally be 65, using the
-standard increments of 50, 10, and 5.
-
-linewidths and edgecolors can be used to customize the barb.
-Additional :class:`~matplotlib.collections.PolyCollection` keyword
-arguments:
+Other Parameters
+----------------
+**kwargs
+    The barbs can further be customized using `.PolyCollection` keyword
+    arguments:
 
-%(PolyCollection)s
+    %(PolyCollection)s
 """ % docstring.interpd.params
 
 docstring.interpd.update(barbs_doc=_barbs_doc)
