8000 eventplot and EventCollection docstrings overhaul (+ make the latter … · matplotlib/matplotlib@93d9e2e · GitHub
[go: up one dir, main page]
Skip to content

Commit 93d9e2e

Browse files
afvincentafvincent
committed
eventplot and EventCollection docstrings overhaul (+ make the latter consistent with its behavior)
1 parent c03df1f commit 93d9e2e

File tree

3 files changed

+97
-70
lines changed

3 files changed

+97
-70
lines changed

‎lib/matplotlib/axes/_axes.py

Lines changed: 57 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1091,55 +1091,83 @@ def eventplot(self, positions, orientation='horizontal', lineoffsets=1,
10911091
linelengths=1, linewidths=None, colors=None,
10921092
linestyles='solid', **kwargs):
10931093
"""
1094-
Plot identical parallel lines at specific positions.
1094+
Plot identical parallel lines at the given positions.
10951095
1096-
Plot parallel lines at the given positions. positions should be a 1D
1097-
or 2D array-like object, with each row corresponding to a row or column
1098-
of lines.
1096+
*positions* should be a 1D or 2D array-like object, with each row
1097+
corresponding to a row or column of lines.
10991098
11001099
This type of plot is commonly used in neuroscience for representing
1101-
neural events, where it is commonly called a spike raster, dot raster,
1100+
neural events, where it is usually called a spike raster, dot raster,
11021101
or raster plot.
11031102
11041103
However, it is useful in any situation where you wish to show the
11051104
timing or position of multiple sets of discrete events, such as the
11061105
arrival times of people to a business on each day of the month or the
11071106
date of hurricanes each year of the last century.
11081107
1109-
*orientation* : [ 'horizontal' | 'vertical' ]
1110-
'horizontal' : the lines will be vertical and arranged in rows
1111-
'vertical' : lines will be horizontal and arranged in columns
1108+
Parameters
1109+
----------
1110+
positions : 1D or 2D array-like object
1111+
Each value is an event. If *positions* is a 2D array-like, each
1112+
row corresponds to a row or a column of lines (depending on the
1113+
*orientation* parameter).
11121114
1113-
*lineoffsets* :
1114-
A float or array-like containing floats.
1115+
orientation : {'horizontal', 'vertical'}, optional
1116+
Controls the direction of the event collections:
11151117
1116-
*linelengths* :
1117-
A float or array-like containing floats.
1118+
- 'horizontal' : the lines are arranged horizontally in rows,
1119+
and are vertical.
1120+
- 'vertical' : the lines are arranged vertically in columns,
1121+
and are horizontal.
11181122
1119-
*linewidths* :
1120-
A float or array-like containing floats.
1123+
lineoffsets : scalar or sequence of scalars, optional, default: 1
1124+
The offset of the center of the lines from the origin, in the
1125+
direction orthogonal to *orientation*.
11211126
1122-
*colors*
1123-
must be a sequence of RGBA tuples (e.g., arbitrary color
1124-
strings, etc, not allowed) or a list of such sequences
1127+
linelengths : scalar or sequence of scalars, optional, default: 1
1128+
The total height of the lines (i.e. the lines stretches from
1129+
``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
11251130
1126-
*linestyles* :
1127-
[ 'solid' | 'dashed' | 'dashdot' | 'dotted' ] or an array of these
1128-
values
1131+
linewidths : scalar, scalar sequence or None, optional, default: None
1132+
The line width(s) of the event lines, in points. If it is None,
1133+
defaults to its rcParams setting.
11291134
1130-
For linelengths, linewidths, colors, and linestyles, if only a single
1131-
value is given, that value is applied to all lines. If an array-like
1132-
is given, it must have the same length as positions, and each value
1133-
will be applied to the corresponding row or column in positions.
1135+
colors : color, sequence of colors or None, optional, default: None
1136+
The color(s) of the event lines. If it is None, defaults to its
1137+
rcParams setting.
11341138
1135-
Returns a list of :class:`matplotlib.collections.EventCollection`
1136-
objects that were added.
1139+
linestyles : str or tuple or a sequence of such values, optional
1140+
Default is 'solid'. Valid strings are ['solid', 'dashed',
1141+
'dashdot', 'dotted', '-', '--', '-.', ':']. Dash tuples
1142+
should be of the form::
11371143
1138-
kwargs are :class:`~matplotlib.collections.LineCollection` properties:
1144+
(offset, onoffseq),
11391145
1140-
%(LineCollection)s
1146+
where *onoffseq* is an even length tuple of on and off ink
1147+
in points.
11411148
1142-
**Example:**
1149+
**kwargs : optional
1150+
Other keyword arguments are line collection properties. See
1151+
:class:`~matplotlib.collections.LineCollection` for a list of
1152+
the valid properties.
1153+
1154+
Returns
1155+
-------
1156+
1157+
A list of :class:`matplotlib.collections.EventCollection` objects that
1158+
were added.
1159+
1160+
Notes
1161+
-----
1162+
1163+
For *linelengths*, *linewidths*, *colors*, and *linestyles*, if only
1164+
a single value is given, that value is applied to all lines. If an
1165+
array-like is given, it must have the same length as *positions*, and
1166+
each value will be applied to the corresponding row or column of
1167+
events.
1168+
1169+
Example
1170+
-------
11431171
11441172
.. plot:: mpl_examples/pylab_examples/eventplot_demo.py
11451173
"""

‎lib/matplotlib/collections.py

Lines changed: 39 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1243,15 +1243,15 @@ class EventCollection(LineCollection):
12431243
'''
12441244
A collection of discrete events.
12451245
1246-
An event is a 1-dimensional value, usually the position of something along
1247-
an axis, such as time or length. Events do not have an amplitude. They
1248-
are displayed as v
1246+
The events are given by a 1-dimensional array, usually the position of
1247+
something along an axis, such as time or length. They do not have an
1248+
amplitude and are displayed as vertical or horizontal parallel bars.
12491249
'''
12501250

12511251
_edge_default = True
12521252

12531253
def __init__(self,
1254-
positions, # Can be None.
1254+
positions, # Cannot be None.
12551255
orientation=None,
12561256
lineoffset=0,
12571257
linelength=1,
@@ -1262,62 +1262,60 @@ def __init__(self,
12621262
**kwargs
12631263
):
12641264
"""
1265-
*positions*
1266-
a sequence of numerical values or a 1D numpy array. Can be None
1267-
1268-
*orientation* [ 'horizontal' | 'vertical' | None ]
1269-
defaults to 'horizontal' if not specified or None
1265+
Parameters
1266+
----------
1267+
positions : 1D array-like object
1268+
Each value is an event.
12701269
1271-
*lineoffset*
1272-
a single numerical value, corresponding to the offset of the center
1273-
of the markers from the origin
1270+
orientation : {None, 'horizontal', 'vertical'}, optional
1271+
The orientation of the **collection** (the event bars are along
1272+
the orthogonal direction). Defaults to 'horizontal' if not
1273+
specified or None.
12741274
1275-
*linelength*
1276-
a single numerical value, corresponding to the total height of the
1277-
marker (i.e. the marker stretches from lineoffset+linelength/2 to
1278-
lineoffset-linelength/2). Defaults to 1
1275+
lineoffset : scalar, optional, default: 0
1276+
The offset of the center of the markers from the origin, in the
1277+
direction orthogonal to *orientation*.
12791278
1280-
*linewidth*
1281-
a single numerical value
1279+
linelength : scalar, optional, default: 1
1280+
The total height of the marker (i.e. the marker stretches from
1281+
``lineoffset - linelength/2`` to ``lineoffset + linelength/2``).
12821282
1283-
*color*
1284-
must be a sequence of RGBA tuples (e.g., arbitrary color
1285-
strings, etc, not allowed).
1283+
linewidth : scalar or None, optional, default: None
1284+
If it is None, defaults to its rcParams setting, in sequence form.
12861285
1287-
*linestyle* [ 'solid' | 'dashed' | 'dashdot' | 'dotted' ]
1286+
color : color, sequence of colors or None, optional, default: None
1287+
If it is None, defaults to its rcParams setting, in sequence form.
12881288
1289-
*antialiased*
1290-
1 or 2
1289+
linestyle : str or tuple, optional, default: 'solid'
1290+
Valid strings are ['solid', 'dashed', 'dashdot', 'dotted',
1291+
'-', '--', '-.', ':']. Dash tuples should be of the form::
12911292
1292-
If *linewidth*, *color*, or *antialiased* is None, they
1293-
default to their rcParams setting, in sequence form.
1293+
(offset, onoffseq),
12941294
1295-
*norm*
1296-
None (optional for :class:`matplotlib.cm.ScalarMappable`)
1297-
*cmap*
1298-
None (optional for :class:`matplotlib.cm.ScalarMappable`)
1295+
where *onoffseq* is an even length tuple of on and off ink
1296+
in points.
12991297
1300-
*pickradius* is the tolerance for mouse clicks picking a line.
1301-
The default is 5 pt.
1298+
antialiased : {None, 1, 2}, optional
1299+
If it is None, defaults to its rcParams setting, in sequence form.
13021300
1303-
The use of :class:`~matplotlib.cm.ScalarMappable` is optional.
1304-
If the :class:`~matplotlib.cm.ScalarMappable` array
1305-
:attr:`~matplotlib.cm.ScalarMappable._A` is not None (i.e., a call to
1306-
:meth:`~matplotlib.cm.ScalarMappable.set_array` has been made), at
1307-
draw time a call to scalar mappable will be made to set the colors.
1301+
**kwargs : optional
1302+
Other keyword arguments are line collection properties. See
1303+
:class:`~matplotlib.collections.LineCollection` for a list of
1304+
the valid properties.
13081305
1309-
**Example:**
1306+
Example
1307+
-------
13101308
13111309
.. plot:: mpl_examples/pylab_examples/eventcollection_demo.py
13121310
"""
13131311

13141312
segment = (lineoffset + linelength / 2.,
13151313
lineoffset - linelength / 2.)
1316-
if len(positions) == 0:
1314+
if positions is None or len(positions) == 0:
13171315
segments = []
13181316
elif hasattr(positions, 'ndim') and positions.ndim > 1:
1319-
raise ValueError('if positions is an ndarry it cannot have '
1320-
'dimensionality great than 1 ')
1317+
raise ValueError('positions cannot have a dimensionality greater '
1318+
'than 1 (in the ndarray sense)')
13211319
elif (orientation is None or orientation.lower() == 'none' or
13221320
orientation.lower() == 'horizontal'):
13231321
positions.sort()

‎lib/matplotlib/tests/test_axes.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2937,6 +2937,7 @@ def test_eventplot_colors(colors):
29372937
for coll, color in zip(collections, expected):
29382938
assert_allclose(coll.get_color(), color)
29392939

2940+
29402941
@image_comparison(baseline_images=['test_eventplot_problem_kwargs'],
29412942
extensions=['png'], remove_text=True)
29422943
def test_eventplot_problem_kwargs():

0 commit comments

Comments
 (0)
0