root/README.html

Revision 1, 13.9 kB (checked in by grig, 5 years ago)

Initial import

Line 
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4   <title>Sparkplot: sparklines in Python using matplotlib</title>
5 </head>
6 <body>
7 <h1 class="title">sparkplot: creating sparklines in Python with
8 matplotlib</h1>
9 <h2><a name="What_is_sparkplot"></a>What is sparkplot?</h2>
10 Sparkplot is a Python module that uses the <a
11  href="http://matplotlib.sourceforge.net/">matplotlib</a> plotting
12 library to create <span style="font-weight: bold;">sparklines</span>.
13 If you're in a hurry, you can download sparkplot from <a
14  href="http://www.sparkplot.org/v1/sparkplot.py">here</a>, then read
15 below for <a href="#Sparkplot_installation_and_usage">installation and
16 usage instructions</a>.<br>
17 <br>
18 <a href="http://www.edwardtufte.com/tufte/">Edward Tufte</a> introduced
19 sparklines in a <a
20  href="http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0001OR&amp;topic_id=1">sample
21 chapter</a> of his upcoming book "Beautiful Evidence". In his words,
22 sparklines are "<span style="font-style: italic;">small,
23 high-resolution graphics embedded in a context of words, numbers,
24 images. Sparklines are data-intense, design-simple, word-sized graphics</span>."
25 <br>
26 <span class="toc-backref"></span><br>
27 <h2><a name="Sparkline_examples"></a>Sparkline examples</h2>
28 The following examples of sparkline graphics were created with
29 sparkplot.<span style="font-weight: bold;"><br>
30 </span>
31 <h4><span style="font-weight: bold;">Example 1</span></h4>
32 Here is the Los Angeles Lakers' road to their NBA title <img
33  src="http://www.sparkplot.org/images/lakers2002.png"
34  border="0"> in 2002. Wins are pictured with blue bars and losses with
35 red bars. Note how easy it is to see the streaks for wins and losses.
36 The Lakers' 2004 <img
37  src="http://www.sparkplot.org/images/lakers2004.png" border="0">
38 season was their last with Shaq, when they reached the NBA
39 finals and lost to Detroit (note the last 3 losses which sealed their
40 fate in the finals).
41 Compare those days of glory with their abysmal <img
42  src="http://www.sparkplot.org/images/lakers2005.png" border="0"> 2005
43 performance, with only 2 wins in the last 21 games.
44 Also note how the width of the last graphic is less than the previous
45 2, a consequence of the Lakers not making the playoffs this year.
46 <span style="font-weight: bold;"><br>
47 </span>
48 <h4><span style="font-weight: bold;">Example 2</span></h4>
49 The southern oscillation is defined as the barometric pressure
50 difference between Tahiti and the Darwin Islands at sea level. The
51 southern oscillation is a predictor of El Nino which in turn is thought
52 to be a driver of world-wide weather. Specifically, repeated southern
53 oscillation values less than -1 typically defines an El Nino.
54 Here is a sparkline for the southern oscillation from
55 1955<img src="http://www.sparkplot.org/images/southern_oscillation.png">to
56 1992 (456 sample data points obtained from NIST). The sparkline is
57 plotted with a horizontal span drawn along the x axis covering data
58 values between -1 and 0, so that values less than -1 can be more
59 clearly seen.
60 <span style="font-weight: bold;"><br>
61 </span>
62 <h4><span style="font-weight: bold;">Example 3</span></h4>
63 Here is the per capita income in California from 1959 <img
64  src="http://www.sparkplot.org/images/CA_percapita_income.png"
65  border="0">to 2003.
66 And here is the "real" per capita income (adjusted for inflation) in
67 California, from 1959 <img
68  src="http://www.sparkplot.org/images/CA_real_percapita_income.png"
69  border="0">to 2003.
70 <span style="font-weight: bold;"><br>
71 </span>
72 <h4><span style="font-weight: bold;">Example 4</span></h4>
73 Here is the monthly distribution of messages sent to comp.lang.py from
74 1994 to 2004, plotted per year. Minimum and maximum values are shown
75 with blue dots and labeled in the graphics.<br>
76 <br>
77 <table border="0">
78   <tbody>
79     <tr>
80       <td style="font-weight: bold;">Year </td>
81       <td style="font-weight: bold;"><br>
82       </td>
83       <td style="font-weight: bold;">Total </td>
84     </tr>
85     <tr>
86       <td>1994 </td>
87       <td><img alt="clpy 1994"
88  src="http://www.sparkplot.org/images/clpy_1994.png" border="0"></td>
89       <td>3,018 </td>
90     </tr>
91     <tr>
92       <td>1995 </td>
93       <td><img alt="clpy 1995"
94  src="http://www.sparkplot.org/images/clpy_1995.png" border="0"></td>
95       <td>4,026 </td>
96     </tr>
97     <tr>
98       <td>1996 </td>
99       <td><img alt="clpy 1996"
100  src="http://www.sparkplot.org/images/clpy_1996.png" border="0"></td>
101       <td>8,378 </td>
102     </tr>
103     <tr>
104       <td>1997 </td>
105       <td><img alt="clpy 1997"
106  src="http://www.sparkplot.org/images/clpy_1997.png" border="0"></td>
107       <td>12,910 </td>
108     </tr>
109     <tr>
110       <td>1998 </td>
111       <td><img alt="clpy 1998"
112  src="http://www.sparkplot.org/images/clpy_1998.png" border="0"></td>
113       <td style="">19,533 </td>
114     </tr>
115     <tr>
116       <td style="">1999 </td>
117       <td style=""><img alt="clpy 1999"
118  src="http://www.sparkplot.org/images/clpy_1999.png" border="0"></td>
119       <td style="">24,725 </td>
120     </tr>
121     <tr>
122       <td style="">2000 </td>
123       <td style=""><img alt="clpy 2000"
124  src="http://www.sparkplot.org/images/clpy_2000.png" border="0"></td>
125       <td style="">42,961 </td>
126     </tr>
127     <tr>
128       <td style="">2001 </td>
129       <td style=""><img alt="clpy 2001"
130  src="http://www.sparkplot.org/images/clpy_2001.png" border="0"></td>
131       <td style="">55,271 </td>
132     </tr>
133     <tr>
134       <td style="">2002 </td>
135       <td style=""><img alt="clpy 2002"
136  src="http://www.sparkplot.org/images/clpy_2002.png" border="0"></td>
137       <td style="">56,750 </td>
138     </tr>
139     <tr>
140       <td style="">2003 </td>
141       <td style=""><img alt="clpy 2003"
142  src="http://www.sparkplot.org/images/clpy_2003.png" border="0"></td>
143       <td style="">64,548 </td>
144     </tr>
145     <tr>
146       <td style="">2004 </td>
147       <td style=""><img alt="clpy 2004"
148  src="http://www.sparkplot.org/images/clpy_2004.png" border="0"></td>
149       <td style="">56,184</td>
150     </tr>
151   </tbody>
152 </table>
153 There was an almost constant increase in the number of messages per
154 year, from 1994 <img
155  src="http://www.sparkplot.org/images/clpy_totals.png" border="0">to
156 2004, the only exception being 2004, when there were
157 fewer message than in 2002 and 2003.<span
158  style="text-decoration: underline;"><br>
159 <br>
160 </span>
161 <h2><a name="Sparkplot_installation_and_usage"></a>Sparkplot
162 installation and usage<span style="text-decoration: underline;"></span></h2>
163 <h2><span style="text-decoration: underline;"></span></h2>
164 <span style="text-decoration: underline;"></span><span
165  class="toc-backref"></span>
166 1) Install the <a
167  href="http://sourceforge.net/project/showfiles.php?group_id=1369&amp;package_id=1351">Numeric
168 Python module</a> or the <a
169  href="http://sourceforge.net/project/showfiles.php?group_id=1369&amp;package_id=32367">numarray
170 Python module</a> (required by matplotlib).<br>
171 2) Install <a
172  href="http://sourceforge.net/project/showfiles.php?group_id=80706&amp;package_id=82474">matplotlib</a>.<br>
173 3) Download <a href="http://www.sparkplot.org/v1/sparkplot.py">sparkplot</a>.<br>
174 4) Prepare data files: sparkplot simplistically assumes that its input
175 data file contains just 1 column of numbers.<br>
176 5) Run sparkplot.py. <br>
177 <br>
178 Here are some command-line examples to get you
179 going:
180 <br>
181 <br>
182 <span style="font-weight: bold;">Example 1</span><br>
183 <br>
184 - given only the input file and no other option, sparkplot.py will
185 generate a gray sparkline with the first and last data points plotted
186 in red<br>
187 <br>
188 Running<br>
189 <span style="font-weight: bold; font-size: 85%;"><span
190  style="font-family: courier new;"><br>
191 sparkplot.py -i
192 CA_real_percapita_income.txt</span></span>
193 <br>
194 produces:<img
195  src="http://www.sparkplot.org/images/CA_real_percapita_income_v1.png"
196  border="0">
197 <br>
198 <br>
199 The name of the output file is by default <span
200  style="font-family: monospace;">input_file_name_with_no_extension</span><input_filename_without_extension><span
201  style="font-family: monospace;">.png</span>.
202 It can be changed with the<span style="font-family: monospace;"> -o</span>
203 option.
204 The plotting of the first and last data points can be disabled with the
205 <span style="font-family: monospace;">--noplot_first</span> and <span
206  style="font-family: monospace;">--noplot_last</span> options.
207 <br>
208 <br>
209 <span style="font-weight: bold;">Example 2</span><br>
210 <br>
211 - given the input file and the <span style="font-family: monospace;">--label_first
212 --label_last --format=currency</span>
213 options, sparkplot.py will generate a gray sparkline with the first and
214 last data points plotted in red and with the first and last data values
215 displayed in a currency format<br>
216 <br>
217 Running<br>
218 <br>
219 <span style="font-size: 85%;"><span
220  style="font-weight: bold; font-family: courier new;">sparkplot.py -i
221 CA_real_percapita_income.txt --label_first --label_last
222 --format=currency</span></span><br>
223 produces:<img
224  src="http://www.sparkplot.org/images/CA_real_percapita_income_v2.png"
225  border="0">
226 <br>
227 <br>
228 The currency symbol is $ by default, but it can be changed with the
229 <span style="font-family: monospace;">--currency</span> option.
230 </input_filename_without_extension><br>
231 <br>
232 <span style="font-weight: bold;">Example 3</span><br>
233 <br>
234 - given the input file and the
235 <span style="font-family: monospace;">--plot_min --plot_max --label_min
236 --label_max --format=comma</span> options,
237 sparkplot.py will generate a gray sparkline with the first and last
238 data points plotted in red, with the min. and max. data points plotted
239 in blue, and with the min. and max. data values displayed in a 'comma'
240 format (e.g. 23,456,789)<br>
241 <br>
242 Running<br>
243 <span style="font-size: 85%;"><span
244  style="font-weight: bold; font-family: courier new;"><br>
245 sparkplot.py -i
246 clpy_1997.txt --plot_min --plot_max --label_min --label_max
247 --format=comma</span></span>
248 <br>
249 produces:<img src="http://www.sparkplot.org/images/clpy_1997.png"
250  border="0">
251 <br>
252 <br>
253 <span style="font-weight: bold;">Example 4</span><br>
254 <br>
255 - given the input file and the <span style="font-family: monospace;">--type=bars</span>
256 option, sparkplot.py will draw
257 blue bars for the positive data values and red bars for the negative
258 data values<br>
259 <br>
260 Running<br>
261 <br>
262 <span style="font-size: 85%;"><span
263  style="font-weight: bold; font-family: courier new;">sparkplot.py -i
264 lakers2005.txt --type=bars</span></span>
265 <br>
266 <br>
267 produces:<img src="http://www.sparkplot.org/images/lakers2005.png"
268  border="0">
269 <br>
270 <br>
271 As a side note, I think bar plots look better when the data file
272 contains a relatively large number of data points, and the variation of
273 the data is relatively small. This type of plots works especially well
274 for sports-related graphics, where wins are represented as +1 and
275 losses as -1.
276 <br>
277 <br>
278 <span style="font-weight: bold;">Example 5</span><br>
279 <br>
280 - given the input file and the <span style="font-family: monospace;">-t</span>
281 or <span style="font-family: monospace;">--transparency</span> option,
282 sparkplot.py will generate a transparent background for the PNG image
283 it produces<br>
284 <br>
285 Running<br>
286 <br>
287 <span style="font-size: 85%;"><span
288  style="font-weight: bold; font-family: courier new;">sparkplot.py -i
289 CA_real_percapita_income.txt -t<br>
290 </span></span><br>
291 produces a transparent-background image, which is shown here on top of
292 a table cell with a yellow background:
293 <table style="width: 150px; text-align: left;" border="0"
294  cellpadding="2" cellspacing="2">
295   <tbody>
296     <tr>
297       <td
298  style="vertical-align: top; background-color: rgb(255, 255, 153);"><img
299  src="http://www.sparkplot.org/images/CA_real_percapita_income_transparent.png"
300  border="0"></td>
301     </tr>
302   </tbody>
303 </table>
304 &nbsp;
305 <br>
306 <br>
307 For other sparkplot options, run <span style="font-size: 85%;"><span
308  style="font-weight: bold; font-family: courier new;"> sparkplot.py -h<br>
309 <br>
310 </span></span>
311 <h2><a name="Other_sparkline_implementations"></a>Other sparkline
312 implementations</h2>
313 <ul>
314   <li>Joe Gregorio has a <a
315  href="http://bitworking.org/news/Sparklines_in_data_URIs_in_Python">Python
316 implementation of sparklines</a> that uses <a
317  href="http://www.ietf.org/rfc/rfc2397">data: URI</a> to embed them
318 into HTML pages</li>
319   <li>There is also a <a
320  href="http://www.whytheluckystiff.net/bumpspark/">Ruby implementation</a>
321 of the data: URI mechanism<br>
322   </li>
323   <li>James Byers has a <a href="http://sparkline.org/">PHP
324 implementation of sparklines</a> using a GD backend</li>
325   <li>A <a
326  href="http://www.edwardtufte.com/bboard/q-and-a-fetch-msg?msg_id=0000Lk&amp;topic_id=1">topic</a>
327 on the <a href="http://www.edwardtufte.com/bboard/q-and-a?topic_id=1">Ask
328 E.T. forum</a> on Edward Tufte's site is dedicated to various sparkline
329 implementations<br>
330   </li>
331 </ul>
332 <span style="font-size: 85%;"><span
333  style="font-weight: bold; font-family: courier new;"></span></span>
334 <h2><a name="Concluding_thoughts"></a>Concluding thoughts<span
335  style="font-size: 85%;"><span
336  style="font-weight: bold; font-family: courier new;"></span></span></h2>
337 <span style="font-size: 85%;"></span>Kudos to John Hunter, the creator
338 of matplotlib. I found this
339 module extremely powerful and versatile. For a nice introduction to
340 matplotlib, see also John's <a
341  href="http://www.python.org/pycon/2005/papers/18/">talk</a> at
342 PyCon05.<br>
343 <br>
344 I
345 hope the sparkplot module will prove to be useful when
346 you need to include sparkline graphics in your Web pages. All the
347 caveats associated with alpha-level software apply :-) Let me know if
348 you find it useful. I'm very much a beginner at using matplotlib, and
349 as I become more acquainted with it I'll add more functionality to
350 sparkplot.
351 <br>
352 <br>
353 Grig Gheorghiu<br>
354 grig _at_ gheorghiu _dot_ net<br>
355 <a href="http://agiletesting.blogspot.com">agiletesting.blogspot.com</a><br>
356 &nbsp;<span style="font-size: 85%;"><span
357  style="font-weight: bold; font-family: courier new;"></span></span>
358 </body>
359 </html>
Note: See TracBrowser for help on using the browser.