Merge pull request #17329 from timhoffm/doc-eventplot

QuLogic · web-flow · commit de03d418f37a · 2020-05-05T16:02:19.000-04:00
Improve docs of eventplot()
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
@@ -1285,9 +1285,6 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
         """
         Plot identical parallel lines at the given positions.
 
-        *positions* should be a 1D or 2D array-like object, with each row
-        corresponding to a row or column of lines.
-
         This type of plot is commonly used in neuroscience for representing
         neural events, where it is usually called a spike raster, dot raster,
         or raster plot.
@@ -1299,48 +1296,53 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
 
         Parameters
         ----------
-        positions : 1D or 2D array-like object
-            Each value is an event. If *positions* is a 2D array-like, each
-            row corresponds to a row or a column of lines (depending on the
-            *orientation* parameter).
+        positions : array-like or list of array-like
+            A 1D array-like defines the positions of one sequence of events.
+
+            Multiple groups of events may be passed as a list of array-likes.
+            Each group can be styled independently by passing lists of values
+            to *lineoffsets*, *linelengths*, *linewidths*, *colors* and
+            *linestyles*.
+
+            Note that *positions* can be a 2D array, but in practice different
+            event groups usually have different counts so that one will use a
+            list of different-length arrays rather than a 2D array.
 
         orientation : {'horizontal', 'vertical'}, default: 'horizontal'
-            The direction of the event collections:
+            The direction of the event sequence:
 
-            - 'horizontal': the lines are arranged horizontally in rows,
-              and are vertical.
-            - 'vertical': the lines are arranged vertically in columns,
-              and are horizontal.
+            - 'horizontal': the events are arranged horizontally.
+              The indicator lines are vertical.
+            - 'vertical': the events are arranged vertically.
+              The indicator lines are horizontal.
 
         lineoffsets : float or array-like, default: 1
             The offset of the center of the lines from the origin, in the
             direction orthogonal to *orientation*.
 
-            A sequence must match the dimension of *positions*
-            in the direction of *orientation*.
+            If *positions* is 2D, this can be a sequence with length matching
+            the length of *positions*.
 
         linelengths : float or array-like, default: 1
             The total height of the lines (i.e. the lines stretches from
             ``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
 
-            If a sequence, then *positions* must be 2D and the length
-            must match the first dimension of *positions*.
+            If *positions* is 2D, this can be a sequence with length matching
+            the length of *positions*.
 
-        linewidths : float or array-like or None, default: None
-            The line width(s) of the event lines, in points. If it is None,
-            defaults to its rcParams setting.
+        linewidths : float or array-like, default: :rc:`lines.linewidth`
+            The line width(s) of the event lines, in points.
 
-            If a sequence, then *positions* must be 2D and the length
-            must match the first dimension of *positions*.
+            If *positions* is 2D, this can be a sequence with length matching
+            the length of *positions*.
 
-        colors : color or list of colors or None, default: None
-            The color(s) of the event lines. If it is None, defaults to its
-            rcParams setting.
+        colors : color or list of colors, default: :rc:`lines.color`
+            The color(s) of the event lines.
 
-            If a sequence, then *positions* must be 2D and the length
-            must match the first dimension of *positions*.
+            If *positions* is 2D, this can be a sequence with length matching
+            the length of *positions*.
 
-        linestyles : str or tuple or a sequence of such values, optional
+        linestyles : str or tuple or list of such values, default: 'solid'
             Default is 'solid'. Valid strings are ['solid', 'dashed',
             'dashdot', 'dotted', '-', '--', '-.', ':']. Dash tuples
             should be of the form::
@@ -1350,11 +1352,10 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
             where *onoffseq* is an even length tuple of on and off ink
             in points.
 
-            If a sequence, then *positions* must be 2D and the length
-            must match the first dimension of *positions*.
-
+            If *positions* is 2D, this can be a sequence with length matching
+            the length of *positions*.
 
-        **kwargs : optional
+        **kwargs
             Other keyword arguments are line collection properties.  See
             `.LineCollection` for a list of the valid properties.
 
diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py
@@ -1448,7 +1448,7 @@ class EventCollection(LineCollection):
 
     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.
+    amplitude and are displayed as parallel lines.
     """
 
     _edge_default = True
@@ -1471,8 +1471,9 @@ def __init__(self,
             Each value is an event.
 
         orientation : {'horizontal', 'vertical'}, default: 'horizontal'
-            The orientation of the **collection** (the event bars are along
-            the orthogonal direction).
+            The sequence of events is plotted along this direction.
+            The marker lines of the single events are along the orthogonal
+            direction.
 
         lineoffset : float, default: 0
             The offset of the center of the markers from the origin, in the
@@ -1482,11 +1483,11 @@ def __init__(self,
             The total height of the marker (i.e. the marker stretches from
             ``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
 
-        linewidth : float or None, default: None
-            If it is None, defaults to its rcParams setting, in sequence form.
+        linewidth : float, default: :rc:`lines.linewidth`
+            The line width of the event lines, in points.
 
-        color : color, sequence of colors or None, default: None
-            If it is None, defaults to its rcParams setting, in sequence form.
+        color : color or list of colors, default: :rc:`lines.color`
+            The color of the event lines.
 
         linestyle : str or tuple, default: 'solid'
             Valid strings are ['solid', 'dashed', 'dashdot', 'dotted',
@@ -1497,10 +1498,10 @@ def __init__(self,
             where *onoffseq* is an even length tuple of on and off ink
             in points.
 
-        antialiased : {None, 1, 2}, optional
-            If it is None, defaults to its rcParams setting, in sequence form.
+        antialiased : bool, default: :rc:`lines.antialiased`
+            Whether to use antialiasing for drawing the lines.
 
-        **kwargs : optional
+        **kwargs
             Other keyword arguments are line collection properties.  See
             :class:`~matplotlib.collections.LineCollection` for a list of
             the valid properties.
