Skip to content

Commit c76b976

Browse files
tacaswelltacaswell
committed
DOC : more work on documentation
1 parent 58610f4 commit c76b976

File tree

1 file changed

+141
-41
lines changed

1 file changed

+141
-41
lines changed

‎doc/users/cycler.rst

+141-41
Original file line numberDiff line numberDiff line change
@@ -81,90 +81,151 @@ kwarg iterator, was developed.
8181
`Cycler` Usage
8282
==============
8383

84-
A 'base' `Cycler` object is some what useful and can be used to easily
85-
cycle over a single style
84+
Basic
85+
-----
8686

87-
.. plot::
88-
:include-source:
87+
A 'base' `Cycler` object is somewhat useful and can be used to easily
88+
cycle over a single style. To create a base `Cycler` use the `cycler`
89+
function to link a key/style/kwarg to series of values. The key can be
90+
any hashable object (as it will eventually be used as the key in a `dict`).
91+
92+
.. ipython:: python
8993
94+
from __future__ import print_function
9095
from matplotlib.cycler import cycler
91-
from itertools import cycle
9296
93-
fig, (ax1, ax2) = plt.subplots(1, 2, tight_layout=True, figsize=(8, 4))
94-
x = np.arange(10)
9597
96-
color_cycle = cycler('c', ['r', 'g', 'b'])
98+
color_cycle = cycler('color', ['r', 'g', 'b'])
99+
color_cycle
97100
98-
for i, sty in enumerate(color_cycle):
99-
ax1.plot(x, x*(i+1), **sty)
101+
The `Cycler` object knows it's length and keys:
100102

103+
.. ipython:: python
101104
102-
for i, sty in zip(range(1, 10), cycle(color_cycle)):
103-
ax2.plot(x, x*i, **sty)
104105
106+
len(color_cycle)
107+
color_cycle.keys
108+
109+
Iterating over this object will yield a series of `dicts` keyed on
110+
the key with a single value from the series
105111

106112
.. ipython:: python
107113
108-
from __future__ import print_function
109-
from matplotlib.cycler import cycler
114+
for v in color_cycle:
115+
print(v)
110116
117+
Basic `Cycler` objects can be passed as the second argument to `cycler`
118+
which is copy cyclers to a new key.
111119

112-
color_cycle = cycler('c', ['r', 'g', 'b'])
120+
.. ipython:: python
113121
114-
color_cycle
122+
cycler('ec', color_cycle)
115123
116-
for v in color_cycle:
117-
print(v)
118124
119-
len(color_cycle)
125+
Composition
126+
-----------
120127

128+
A single `Cycler` is not all that useful, they can just as easily be
129+
replaced by a single `for` loop. Fortunately, `Cycler` objects can be
130+
composed to easily generate complex, multi-key cycles.
121131

122-
fig, (ax1, ax2) = plt.subplots(1, 2, tight_layout=True, figsize=(8, 4))
123-
x = np.arange(10)
132+
Addition
133+
~~~~~~~~
124134

135+
Equal length `Cycler` s with different keys can be added to get the
136+
'inner' product of two cycles
125137

126-
for i, sty in enumerate(color_cycle):
127-
ax1.plot(x, x*(i+1), **sty)
138+
.. ipython:: python
139+
140+
lw_cycle = cycler('lw', range(1, 4))
141+
142+
wc = lw_cycle + color_cycle
128143
144+
The result has the same length and has keys which are the union of the
145+
two input `Cycler` s.
129146

147+
.. ipython:: python
148+
149+
len(wc)
150+
wc.keys
151+
152+
and iterating over the result is the zip of the two input cycles
130153

154+
.. ipython:: python
131155
156+
for s in wc:
157+
print(s)
132158
133-
However they are most useful when composed. They can be added
159+
As with arithmetic, addition is commutative
134160

135161
.. ipython:: python
136162
137-
lw_cycle = cycler('lw', range(1, 5))
138-
add_cycle = color_cycle + lw_cycle
163+
for a, b in zip(lw_cycle + color_cycle, color_cycle + lw_cycle):
164+
print(a == b)
139165
140-
lw_cycle
141-
add_cycle
142166
143-
for v in add_cycle:
144-
print(v)
167+
Multiplication
168+
~~~~~~~~~~~~~~
145169

146-
len(add_cycle)
170+
Any pair of `Cycler` can be multiplied
147171

148-
or multiplied
172+
.. ipython:: python
173+
174+
m_cycle = cycler('marker', ['s', 'o'])
175+
176+
m_c = m_cycle * color_cycle
177+
178+
which gives the 'outer product' of the two cycles (same as
179+
:func:`itertools.prod` )
149180

150181
.. ipython:: python
151182
152-
prod_cycle = color_cycle * lw_cycle
183+
len(m_c)
184+
m_c.keys
185+
for s in m_c:
186+
print(s)
187+
188+
Note that unlike addition, multiplication is not commutative (like
189+
matrices)
190+
191+
.. ipython:: python
192+
193+
c_m = color_cycle * m_cycle
194+
for a, b in zip(c_m, m_c):
195+
print(a, b)
196+
197+
198+
199+
200+
Integer Multiplication
201+
~~~~~~~~~~~~~~~~~~~~~~
202+
203+
`Cycler` s can also be multiplied by integer values to increase the length.
204+
205+
.. ipython:: python
206+
207+
color_cycle * 2
208+
2 * color_cycle
153209
154-
color_cycle
155-
lw_cycle
156-
prod_cycle
157210
158-
for v in prod_cycle:
159-
print(v)
160211
161-
len(prod_cycle)
212+
Slicing
213+
-------
162214

163-
The result of composition is another `Cycler` object which allows very
164-
complicated cycles to be defined very succinctly
215+
Cycles can be sliced with `silce` objects
165216

166217
.. ipython:: python
167218
219+
color_cycle[::-1]
220+
color_cycle[:2]
221+
color_cycle[1:]
222+
223+
to return a sub-set of the cycle as a new `Cycler`. They can also be multiplied
224+
by scalars to make fixed length periodic cycles
225+
226+
Examples
227+
--------
228+
168229

169230
.. plot::
170231
:include-source:
@@ -183,3 +244,42 @@ complicated cycles to be defined very succinctly
183244

184245
for i, sty in zip(range(1, 10), cycle(color_cycle)):
185246
ax2.plot(x, x*i, **sty)
247+
248+
249+
.. plot::
250+
:include-source:
251+
252+
from matplotlib.cycler import cycler
253+
from itertools import cycle
254+
255+
fig, (ax1, ax2) = plt.subplots(1, 2, tight_layout=True, figsize=(8, 4))
256+
x = np.arange(10)
257+
258+
color_cycle = cycler('c', ['r', 'g', 'b'])
259+
260+
for i, sty in enumerate(color_cycle):
261+
ax1.plot(x, x*(i+1), **sty)
262+
263+
264+
for i, sty in zip(range(1, 10), cycle(color_cycle)):
265+
ax2.plot(x, x*i, **sty)
266+
267+
268+
Exceptions
269+
----------
270+
271+
272+
A `ValueError` is raised if unequal length `Cycler` s are added together
273+
274+
.. ipython:: python
275+
:okexcept:
276+
277+
color_cycle + ls_cycle
278+
279+
or if two cycles which have overlapping keys are composed
280+
281+
.. ipython:: python
282+
:okexcept:
283+
284+
color_cycle + color_cycle
285+
color_cycle * color_cycle

0 commit comments

Comments
 (0)