improve docstring of Axes.plot

timhoffm · timhoffm · commit 1375f72c78f2 · 2018-01-07T21:21:28.000+01:00
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1288,132 +1288,228 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
     @docstring.dedent_interpd
     def plot(self, *args, **kwargs):
         """
-        Plot lines and/or markers to the
-        :class:`~matplotlib.axes.Axes`.  *args* is a variable length
-        argument, allowing for multiple *x*, *y* pairs with an
-        optional format string.  For example, each of the following is
-        legal::
+        Plot lines and/or a series of markers. This is also known as line plot
+        or XY (scatter) plot respectively.
 
-            plot(x, y)        # plot x and y using default line style and color
-            plot(x, y, 'bo')  # plot x and y using blue circle markers
-            plot(y)           # plot y using x as index array 0..N-1
-            plot(y, 'r+')     # ditto, but with red plusses
+        There are different ways how you can use the interface:
 
-        If *x* and/or *y* is 2-dimensional, then the corresponding columns
-        will be plotted.
+        **1. Basic interface**
 
-        If used with labeled data, make sure that the color spec is not
-        included as an element in data, as otherwise the last case
-        ``plot("v","r", data={"v":..., "r":...)``
-        can be interpreted as the first case which would do ``plot(v, r)``
-        using the default line style and color.
+        ::
 
-        If not used with labeled data (i.e., without a data argument),
-        an arbitrary number of *x*, *y*, *fmt* groups can be specified, as in::
+            plot([x,] y)
 
-            a.plot(x1, y1, 'g^', x2, y2, 'g-')
+        The coordinates of the points or line nodes are given by *x*, *y*.
+        Their properties are controlled by keyword arguments, which are
+        `~.Line2D` properties.
 
-        Return value is a list of lines that were added.
+        To plot multiple sets of data, call `.plot` multiple times, or
+        alternatively use 2-dimensional datasets.
 
-        By default, each line is assigned a different style specified by a
-        'style cycle'.  To change this behavior, you can edit the
-        axes.prop_cycle rcParam.
-
-        The following format string characters are accepted to control
-        the line style or marker:
-
-        ================    ===============================
-        character           description
-        ================    ===============================
-        ``'-'``             solid line style
-        ``'--'``            dashed line style
-        ``'-.'``            dash-dot line style
-        ``':'``             dotted line style
-        ``'.'``             point marker
-        ``','``             pixel marker
-        ``'o'``             circle marker
-        ``'v'``             triangle_down marker
-        ``'^'``             triangle_up marker
-        ``'<'``             triangle_left marker
-        ``'>'``             triangle_right marker
-        ``'1'``             tri_down marker
-        ``'2'``             tri_up marker
-        ``'3'``             tri_left marker
-        ``'4'``             tri_right marker
-        ``'s'``             square marker
-        ``'p'``             pentagon marker
-        ``'*'``             star marker
-        ``'h'``             hexagon1 marker
-        ``'H'``             hexagon2 marker
-        ``'+'``             plus marker
-        ``'x'``             x marker
-        ``'D'``             diamond marker
-        ``'d'``             thin_diamond marker
-        ``'|'``             vline marker
-        ``'_'``             hline marker
-        ================    ===============================
+        Typical example::
 
+            plot(x, y, linewidth='2', color='purple')
 
-        The following color abbreviations are supported:
 
-        ==========  ========
-        character   color
-        ==========  ========
-        'b'         blue
-        'g'         green
-        'r'         red
-        'c'         cyan
-        'm'         magenta
-        'y'         yellow
-        'k'         black
-        'w'         white
-        ==========  ========
+        **2. MATLAB-style interface**
 
-        In addition, you can specify colors in many weird and
-        wonderful ways, including full names (``'green'``), hex
-        strings (``'#008000'``), RGB or RGBA tuples (``(0,1,0,1)``) or
-        grayscale intensities as a string (``'0.8'``).  Of these, the
-        string specifications can be used in place of a ``fmt`` group,
-        but the tuple forms can be used only as ``kwargs``.
+        This interface is suitable for simpler use cases, e.g. when quickly
+        drawing something in an interactive session.
 
-        Line styles and colors are combined in a single format string, as in
-        ``'bo'`` for blue circles.
+        ::
 
-        The *kwargs* can be used to set line properties (any property that has
-        a ``set_*`` method).  You can use this to set a line label (for auto
-        legends), linewidth, antialiasing, marker face color, etc.  Here is an
-        example::
+            plot([x,] y, [fmt,])
+            plot([x,] y, [fmt,], [x2,] y2, [fmt2,], ...)  # multiple data sets
 
-            plot([1,2,3], [1,2,3], 'go-', label='line 1', linewidth=2)
-            plot([1,2,3], [1,4,9], 'rs',  label='line 2')
-            axis([0, 4, 0, 10])
-            legend()
+        You can define basic formatting like color, marker and linestyle using
+        a format string *fmt*. The formats are explained in the *Notes*
+        section below.
 
-        If you make multiple lines with one plot command, the kwargs
-        apply to all those lines, e.g.::
+        Multiple sets of *x*, *y*, *[fmt]* groups can be given. In this case,
+        any additional keyword arguments apply to all data sets.
 
-            plot(x1, y1, x2, y2, antialiased=False)
+        Typical examples::
 
-        Neither line will be antialiased.
+            plot(x, y, 'ro')          # plot x and y using blue circle markers
+            plot(x1, y1, 'g^', x2, y2, 'g-')           # plot two sets of data
 
-        You do not need to use format strings, which are just
-        abbreviations.  All of the line properties can be controlled
-        by keyword arguments.  For example, you can set the color,
-        marker, linestyle, and markercolor with::
 
-            plot(x, y, color='green', linestyle='dashed', marker='o',
-                 markerfacecolor='blue', markersize=12).
+        **3. Labelled data interface**
 
-        See :class:`~matplotlib.lines.Line2D` for details.
+        For objects with labelled data (i.e. data that can be accessed by
+        index ``obj['y']``) you can specify the labels to plot and provide
+        the object in the *data* parameter::
 
-        The kwargs are :class:`~matplotlib.lines.Line2D` properties:
+            plot(ylabel, data=obj)
+            plot(xlabel, ylabel, fmt, data=obj)
 
-        %(Line2D)s
+        All indexable objects are supported. This could e.g. be a `dict`, a
+        `pandas.DataFame` or a structured numpy array.
+
+        .. note::
+            The signature ``plot(xlabel, ylabel, data=obj)`` without a format
+            string is not supported because it would be ambiguous with
+            ``plot(ylabel, fmt, data=obj)``. In such a case, you can use an
+            empty format string::
+
+                plot(xlabel, ylabel, '', data=obj)
+
+        Typical example::
+
+            plot('year', 'happiness', 'b-', data=world_happiness_report)
+
+        Parameters
+        ----------
+        x, y, x2, y2, ... : array-like or scalar
+            The horizontal / vertical coordinates of the data points.
+            *x* values are optional. If not given, they default to
+            ``[0, ..., N-1]``.
+
+            Commonly, these parameters are arrays of length N. However,
+            scalars are supported as well (equivalent to an array with
+            constant value).
+
+            The parameters can also be 2-dimensional. Then, the columns
+            represent separate data sets.
+
+        fmt : str, optional
+            A format string, e.g. 'ro' for red circles. See the *Notes*
+            section for a full description of the format strings.
+
+            Format strings are just an abbreviation for quickly setting
+            basic line properties. All of these and more can also be
+            controlled by keyword arguments.
+
+        data : indexable object, optional
+            The data object for using the labelled data interface.
+
+        Other Parameters
+        ----------------
+        scalex, scaley : bool, optional, default: True
+            These parameters determined if the view limits are adapted to
+            the data limits. The values are passed on to `autoscale_view`.
+
+        **kwargs : `~.Line2D` properties, optional
+            *kwargs* are used to specify roperties like a line label (for
+            auto legends), linewidth, antialiasing, marker face color.
+            Example::
+
+                plot([1,2,3], [1,2,3], 'go-', label='line 1', linewidth=2)
+                plot([1,2,3], [1,4,9], 'rs',  label='line 2')
+
+            If you make multiple lines with one plot command, the kwargs
+            apply to all those lines, e.g.::
+
+                plot(x1, y1, x2, y2, antialiased=False)
+
+            Here is a list of available `~.Line2D` properties:
+
+            %(Line2D)s
+
+        Returns
+        -------
+        lines
+            A list of `~.Line2D` objects that were added.
+
+
+        See Also
+        --------
+        scatter : XY scatter plot with markers of variing size (
+            sometimes also called bubble chart).
+
+
+
+        Notes
+        -----
+        By default, each line is assigned a different style specified by a
+        'style cycle'.  The *fmt* and line property parameters are only
+        neccessary if you want explicit deviations from these defaults.
+        Alternatively, you can also change the style cycle using the
+        ``'axes.prop_cycle'`` rcParam.
+
+
+        **Format Strings**
+
+        A format string consists of a part for color, marker and line::
+
+            fmt = '[color][marker][line]'
+
+        Each of them is optional. If not provided, the value from the style
+        cycle is used. Exception: If ``line`` is given, but no ``marker``,
+        the data will be a line without markers.
+
+        **Colors**
+
+        The following color abbreviations are supported:
+
+        =============    ===============================
+        character        color
+        =============    ===============================
+        ``'b'``          blue
+        ``'g'``          green
+        ``'r'``          red
+        ``'c'``          cyan
+        ``'m'``          magenta
+        ``'y'``          yellow
+        ``'k'``          black
+        ``'w'``          white
+        =============    ===============================
+
+        In addition, you can specify colors in many weird and
+        wonderful ways, including full names (``'green'``), hex
+        strings (``'#008000'``), RGB or RGBA tuples (``(0,1,0,1)``) or
+        grayscale intensities as a string (``'0.8'``).  Of these, the
+        string specifications can be used in place of a ``fmt`` group,
+        but the tuple forms can be used only as ``kwargs``.
+
+        **Markers**
+
+        =============    ===============================
+        character        description
+        =============    ===============================
+        ``'.'``          point marker
+        ``','``          pixel marker
+        ``'o'``          circle marker
+        ``'v'``          triangle_down marker
+        ``'^'``          triangle_up marker
+        ``'<'``          triangle_left marker
+        ``'>'``          triangle_right marker
+        ``'1'``          tri_down marker
+        ``'2'``          tri_up marker
+        ``'3'``          tri_left marker
+        ``'4'``          tri_right marker
+        ``'s'``          square marker
+        ``'p'``          pentagon marker
+        ``'*'``          star marker
+        ``'h'``          hexagon1 marker
+        ``'H'``          hexagon2 marker
+        ``'+'``          plus marker
+        ``'x'``          x marker
+        ``'D'``          diamond marker
+        ``'d'``          thin_diamond marker
+        ``'|'``          vline marker
+        ``'_'``          hline marker
+        =============    ===============================
+
+        **Line Styles**
+
+        =============    ===============================
+        character        description
+        =============    ===============================
+        ``'-'``          solid line style
+        ``'--'``         dashed line style
+        ``'-.'``         dash-dot line style
+        ``':'``          dotted line style
+        =============    ===============================
+
+        Example format strings::
+
+            'b'    # blue markers with default shape
+            'ro'   # red circles
+            'g-'   # green solid line
+            '--'   # dashed line with default color
+            'k^:'  # black triangle_up markers connected by a dotted line
 
-        kwargs *scalex* and *scaley*, if defined, are passed on to
-        :meth:`~matplotlib.axes.Axes.autoscale_view` to determine
-        whether the *x* and *y* axes are autoscaled; the default is
-        *True*.
         """
         scalex = kwargs.pop('scalex', True)
         scaley = kwargs.pop('scaley', True)
