Repository: matplotlib/matplotlib
Pull request: DOC: clarify the expected shapes of eventplot input
closes #16546

Problem statement:
Problem with eventplot - error message claims events & lineoffsets are unequal sizes
### Bug report

**Matplotlib.pyplot eventplot function is raising an error when i try to generate a raster plot. Given a sequence of event timings, and an equally sized sequence of lineoffsets, the error message  'ValueError: lineoffsets and positions are unequal sized sequences' is returned. Changing the dtype to np.array for both variables does not help.**


Reproducible with:

import matplotlib.pyplot as plt

events=[197, 2175, 4153]   # event timings for a single subject
lineoffsets = [1, 1, 1]
plt.eventplot(events, lineoffsets=lineoffsets)

**Actual outcome**
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/nd17878/anaconda3/lib/python3.7/site-packages/matplotlib/pyplot.py", line 2567, in eventplot
    else {}), **kwargs)
  File "/home/nd17878/anaconda3/lib/python3.7/site-packages/matplotlib/__init__.py", line 1589, in inner
    return func(ax, *map(sanitize_sequence, args), **kwargs)
  File "/home/nd17878/anaconda3/lib/python3.7/site-packages/matplotlib/axes/_axes.py", line 1376, in eventplot
    raise ValueError('lineoffsets and positions are unequal sized '
ValueError: lineoffsets and positions are unequal sized sequences
>>> lineoffsets = [1,3]
>>> plt.eventplot(events, lineoffsets=lineoffsets)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/home/nd17878/anaconda3/lib/python3.7/site-packages/matplotlib/pyplot.py", line 2567, in eventplot
    else {}), **kwargs)
  File "/home/nd17878/anaconda3/lib/python3.7/site-packages/matplotlib/__init__.py", line 1589, in inner
    return func(ax, *map(sanitize_sequence, args), **kwargs)
  File "/home/nd17878/anaconda3/lib/python3.7/site-packages/matplotlib/axes/_axes.py", line 1376, in eventplot
    raise ValueError('lineoffsets and positions are unequal sized '
ValueError: lineoffsets and positions are unequal sized sequences
<!--Please tell us how you installed matplotlib and python e.g., from source, pip, conda-->
<!--If you installed from conda, please specify which channel you used if not the default-->

Hints from issue discussion:
You can either create a single event series, like

```
events=[197, 2175, 4153]
lineoffsets = [1]
plt.eventplot(events, lineoffsets=lineoffsets)
```

or 3 series like
```
events=np.array([[197, 2175, 4153]]).T
lineoffsets = [1, 1, 1]
plt.eventplot(events, lineoffsets=lineoffsets)
```

but creating a single series with 3 offsets won't work. Possibly the documentation needs to be improved? Please feel free to make a suggestion.

Commit message: DOC: clarify the expected shapes of eventplot input

closes #16546

Patch to review:
diff --git a/lib/matplotlib/axes/_axes.py b/lib/matplotlib/axes/_axes.py
index 45ceb2c178ba..7f8d9113f978 100644
--- a/lib/matplotlib/axes/_axes.py
+++ b/lib/matplotlib/axes/_axes.py
@@ -1271,18 +1271,30 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
             The offset of the center of the lines from the origin, in the
             direction orthogonal to *orientation*.
 
+            If a sequence, then must match the dimension of *positions*
+            in the direction of *orientation*.
+
         linelengths : scalar or sequence of scalars, 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*.
+
         linewidths : scalar, scalar sequence or None, default: None
             The line width(s) of the event lines, in points. If it is None,
             defaults to its rcParams setting.
 
+            If a sequence, then *positions* must be 2D and the length
+            must match the first dimension of *positions*.
+
         colors : color, sequence of colors or None, default: None
             The color(s) of the event lines. If it is None, defaults to its
             rcParams setting.
 
+            If a sequence, then *positions* must be 2D and the length
+            must match the first dimension of *positions*.
+
         linestyles : str or tuple or a sequence of such values, optional
             Default is 'solid'. Valid strings are ['solid', 'dashed',
             'dashdot', 'dotted', '-', '--', '-.', ':']. Dash tuples
@@ -1293,6 +1305,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*.
+
+
         **kwargs : optional
             Other keyword arguments are line collection properties.  See
             `.LineCollection` for a list of the valid properties.


Code review comments:
diff_hunk: @@ -1271,18 +1271,30 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
             The offset of the center of the lines from the origin, in the
             direction orthogonal to *orientation*.
 
+            If a sequence, then must match the dimension of *positions*
path: lib/matplotlib/axes/_axes.py
text: @user1:
```suggestion
            A sequence must match the dimension of *positions*
```