1"""
2===============
3Line Collection
4===============
5
6Plotting lines with Matplotlib.
7
8`~matplotlib.collections.LineCollection` allows one to plot multiple
9lines on a figure. Below we show off some of its properties.
10"""
11
12import matplotlib.pyplot as plt
13from matplotlib.collections import LineCollection
14from matplotlib import colors as mcolors
15
16import numpy as np
17
18# In order to efficiently plot many lines in a single set of axes,
19# Matplotlib has the ability to add the lines all at once. Here is a
20# simple example showing how it is done.
21
22x = np.arange(100)
23# Here are many sets of y to plot vs. x
24ys = x[:50, np.newaxis] + x[np.newaxis, :]
25
26segs = np.zeros((50, 100, 2))
27segs[:, :, 1] = ys
28segs[:, :, 0] = x
29
30# Mask some values to test masked array support:
31segs = np.ma.masked_where((segs > 50) & (segs < 60), segs)
32
33# We need to set the plot limits.
34fig, ax = plt.subplots()
35ax.set_xlim(x.min(), x.max())
36ax.set_ylim(ys.min(), ys.max())
37
38# *colors* is sequence of rgba tuples.
39# *linestyle* is a string or dash tuple. Legal string values are
40# solid|dashed|dashdot|dotted.  The dash tuple is (offset, onoffseq) where
41# onoffseq is an even length tuple of on and off ink in points.  If linestyle
42# is omitted, 'solid' is used.
43# See `matplotlib.collections.LineCollection` for more information.
44colors = [mcolors.to_rgba(c)
45          for c in plt.rcParams['axes.prop_cycle'].by_key()['color']]
46
47line_segments = LineCollection(segs, linewidths=(0.5, 1, 1.5, 2),
48                               colors=colors, linestyle='solid')
49ax.add_collection(line_segments)
50ax.set_title('Line collection with masked arrays')
51plt.show()
52
53###############################################################################
54# In order to efficiently plot many lines in a single set of axes,
55# Matplotlib has the ability to add the lines all at once. Here is a
56# simple example showing how it is done.
57
58N = 50
59x = np.arange(N)
60# Here are many sets of y to plot vs. x
61ys = [x + i for i in x]
62
63# We need to set the plot limits, they will not autoscale
64fig, ax = plt.subplots()
65ax.set_xlim(np.min(x), np.max(x))
66ax.set_ylim(np.min(ys), np.max(ys))
67
68# colors is sequence of rgba tuples
69# linestyle is a string or dash tuple. Legal string values are
70#          solid|dashed|dashdot|dotted.  The dash tuple is (offset, onoffseq)
71#          where onoffseq is an even length tuple of on and off ink in points.
72#          If linestyle is omitted, 'solid' is used
73# See `matplotlib.collections.LineCollection` for more information
74
75# Make a sequence of (x, y) pairs.
76line_segments = LineCollection([np.column_stack([x, y]) for y in ys],
77                               linewidths=(0.5, 1, 1.5, 2),
78                               linestyles='solid')
79line_segments.set_array(x)
80ax.add_collection(line_segments)
81axcb = fig.colorbar(line_segments)
82axcb.set_label('Line Number')
83ax.set_title('Line Collection with mapped colors')
84plt.sci(line_segments)  # This allows interactive changing of the colormap.
85plt.show()
86
87#############################################################################
88#
89# .. admonition:: References
90#
91#    The use of the following functions, methods, classes and modules is shown
92#    in this example:
93#
94#    - `matplotlib.collections`
95#    - `matplotlib.collections.LineCollection`
96#    - `matplotlib.cm.ScalarMappable.set_array`
97#    - `matplotlib.axes.Axes.add_collection`
98#    - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`
99#    - `matplotlib.pyplot.sci`
100