summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/sparklines/sparklines.tex
blob: 1e038cbd5f373aea6866822fa89a993f7222d48a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
\documentclass{article}

\usepackage{sparklines}

\renewcommand{\baselinestretch}{1.25}
\let\env=\texttt
\let\pkg=\textsf

\definecolor{sparkrectanglecolor}{rgb}{0.8,0.95,0.8}
\definecolor{sparkspikecolor}{rgb}{1,0,0}
\setlength{\sparkdotwidth}{1.3pt}
\setlength{\sparklinethickness}{.3pt}

\begin{document}

\title{Sparklines}
\author{Andreas Loeffler \and Dan Luecking}
\date{Updated 27~December 2016  (version 1.7)}\maketitle

\section{What are sparklines?}

Sparklines are intense, simple, wordlike graphics, so named by Edward
Tufte. This is an example of sparkline:
\begin{sparkline}{10}
% This environment has now an own coordinate system. x and y run from 0 to 1.
%
% This draws a sparkling-rectangle with lower level y=0.3 and upper
% level y=0.8
\sparkrectangle 0.3 0.8
%
% This draws a blue colored sparkling-dot at x=0.5, y=0.62
\sparkdot 0.5 0.62 blue
%
% This draws a red colored sparkling-dot at x=1, y=0.2
\sparkdot 1 0.2 red
%
% This draws a sparkline with ten values starting at x=0.1 and
% y=0.95, then x=0.2 and y=0.8 etc.  Drawing finishes if / appears
\spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 0.52  0.5 0.62
       0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
\end{sparkline}
(the stock price of Daimler Chrysler, for example).
%
In lieu of a more detailed introduction, Professor Tufte's site
has an early release of a chapter on sparklines, see
www.edwardtufte.com. A PHP implementation can be found at
http://sparkline.sourceforge.net/.

A sparkline can be added using the \env{sparkline}--environment.
Also, you can add sparkling rectangles for the median and special
sparkling dots in red or blue. If we want to add a sparkline, be careful not to leave an empty line
between the text left of the sparkline and the environment itself,
since otherwise the sparkline starts a new paragraph.

Sparklines do not appear within a
dvi-file, they require either pdflatex or conversion to postscript with
dvips. The \textsf{sparklines} package requires the \pkg{pgf} package.
This makes it incompatible with \pkg{pictex}: the combination both
require too many dimension parameters. It is possible that the package \pkg{sparklines}
can be used with \pkg{pictexwd}; they can at least be loaded together
without using too many dimensions, but no other test was conducted.


\section{Usage}
\paragraph{Sparkline environment}
The sparkline at the beginning of the previous section was created with the
following:
\begin{verbatim}
  \begin{sparkline}{10}
    \sparkrectangle 0.3 0.8
    \sparkdot 0.5 0.62 blue
    \sparkdot 1 0.2 red
    \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 0.52  0.5 0.62
           0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \end{sparkline}
\end{verbatim}

The argument of the environment gives the width of the graphic as a
multiple of the dimension unit \texttt{ex} (approximately the height of
the lowercase `x' in the current font). Within the environment,
$x$-coordinates run from 0 (extreme left of the graphic) to 1 (extreme
right).

The height of the graphic is given by the \emph{macro}
\verb$\sparklineheight$, defined to produce \texttt{1.75} by default.
The units are the same as for the width: the \texttt{ex} of the current
font. You can redefine that macro (with \verb$\renewcommand$) to force
another height. Within the graphic, the $y$-coordinate runs from 0
(lowermost point) to 1 (uppermost).

Each pair of numbers after the macro \verb$\spark$ represents a
coordinate pair, giving the location of a point in the above described
coordinate system. The macro draws a line from each point to the next.
Each number must be followed by a space, and the list is terminated by a
\texttt{/}. Be careful that there are an even number of coordinates. The
thickness of the line that is created is the value of the length
\verb$\sparklinethickness$, which the user may change (with
\verb$\setlength$). The default value is \texttt{0.2pt}; the above
example was created with the value \texttt{0.3pt}.

\paragraph{Sparkrectangle}
The \verb$\sparkrectangle$ command produces a background rectangle. It
must be followed by two numbers, each followed by a space or the end of
the line. They are the $y$-coordinates of the bottom and top of the
rectangle. This is supposed to show the `normal range' of the $y$-data,
so that a point outside that rectangle represents a departure from
normal. The color of the rectangle is `\texttt{sparkrectanglecolor}',
which the user may redefine (with
\verb$\definecolor$). The initial definition is given by \\
\indent\verb$\definecolor{sparkrectanglecolor}{gray}{0.9}$\\
In the above example, it was first changed to a light green.

\paragraph{Sparkdots}
The colored dots are produced by \verb$\sparkdot$, the diameter of the
dot is the value of the length \verb$\sparkdotwidth$, which the user may
change (with \verb$\setlength$). The default value is \texttt{1.2pt};
the above example was created a value of \texttt{1.3pt}. The command
takes three parameters, each of which must be followed by a space or the
end of the line. The first two are the coordinates of the center of the
dot, the third is the color.

\paragraph{Bar graphs}
Bar graphs can be drawn easily:
\begin{sparkline}{5}
\sparkspike .083 .18
\sparkspike .25 .55
\sparkspike .417 1
\sparkspike .583 .62
\sparkspike .75 .42
\sparkspike .917 .5
\end{sparkline}.
This was created by the code:
\begin{verbatim}
  \begin{sparkline}{5}
    \sparkspike .083 .18
    \sparkspike .25 .55
    \sparkspike .417 1
    \sparkspike .583 .62
    \sparkspike .75 .42
    \sparkspike .917 .5
  \end{sparkline}.
\end{verbatim}
The macro \verb$\sparkspike$ must be followed by a pair of numbers, each
followed by a space or the end of the line. The first of the pair is the
horizontal location of the bar and the second is the height. The bars
are drawn in color `\texttt{sparkspikecolor}' which the user may
redefine (with \verb$\definecolor$). The default is \texttt{black}; the
above example was drawn with it changed to \texttt{red}. The width of
each bar is the value of the length \verb$\sparkspikewidth$, which the
user may change (with \verb$\setlength$). The default is \texttt{2pt}.

You can combine bars and lines:
\begin{sparkline}{5}
  \sparkspike .083 .18
  \sparkspike .25 .55
  \sparkspike .417 1
  \sparkspike .583 .62
  \sparkspike .75 .42
  \sparkspike .917 .5
  \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 0.52  0.5 0.62
  0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \sparkdot 1 0.2 blue
\end{sparkline}\space.  This was created with
\begin{verbatim}
\begin{sparkline}{5}
  \sparkspike .083 .18
  \sparkspike .25 .55
  \sparkspike .417 1
  \sparkspike .583 .62
  \sparkspike .75 .42
  \sparkspike .917 .5
  \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 0.52  0.5 0.62
  0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \sparkdot 1 0.2 blue
\end{sparkline}\space.
\end{verbatim}



\paragraph{Colors} In case you want to change colors use 
\begin{verbatim}
\definecolor{sparkrectanglecolor}{gray}{0.9}
\definecolor{sparkspikecolor}{named}{red}
\definecolor{sparklinecolor}{named}{red}
\end{verbatim}
before the sparkline environment (see a manual about defining colors in \LaTeX{} if you do not understand the definition of \emph{named} etc.).

\paragraph{Bottom line} This adds a bottom line (the x-axis) which can be useful to visually separate different bar charts that are next to each other: 
\begin{sparkline}{5}
\definecolor{sparkbottomlinecolor}{gray}{0.9}
\sparkspike .15 .55
\sparkspike .317 1
\sparkspike .483 .62
\sparkspike .65 .42
\sparkspike .817 .5
\sparkbottomline[0.9] 
\end{sparkline}. 
The code used was 
\begin{verbatim}
  \begin{sparkline}{5}
    \definecolor{sparkbottomlinecolor}{gray}{0.9}
    \sparkspike .15 .55
    \sparkspike .317 1
    \sparkspike .483 .62
    \sparkspike .65 .42
    \sparkspike .817 .5
    \sparkbottomline[0.9]
  \end{sparkline}.
\end{verbatim}
Changing the color of the bottom line is quite easy using the command
like
\begin{verbatim}
\definecolor{sparkbottomlinecolor}{named}{red}
\end{verbatim}.  You can change the thickness of the bottom line using
command like
\begin{verbatim}
\setlength\sparkbottomlinethickness{1pt}
\end{verbatim}

The optional argument of \verb|\sparkbottomline| is the length of the
bottom line (by default~1).

If you need to set both start and end of the bottomline, use
\verb|\sparkbottomlinex| command, which has two obligatory arguments:
the start and the end, for example, 
\definecolor{sparkbottomlinecolor}{named}{blue}%
  \begin{sparkline}{5}
    \sparkspike .15 .55
    \sparkspike .317 1
    \sparkspike .483 .62
    \sparkspike .65 .42
    \sparkspike .817 .5
    \sparkbottomlinex 0.3 0.8
  \end{sparkline}.  This was created with the code
\begin{verbatim}
  \begin{sparkline}{5}
    \sparkspike .15 .55
    \sparkspike .317 1
    \sparkspike .483 .62
    \sparkspike .65 .42
    \sparkspike .817 .5
    \sparkbottomlinex 0.3 0.8
  \end{sparkline}
\end{verbatim}

\paragraph{Clipping}

Sometimes you may have sparklines outside the drawing region, for
example, 
  \begin{sparkline}{10}
    \sparkrectangle 0.3 0.8
    \sparkdot 0.5 0.62 blue
    \sparkdot 1 0.2 red
    \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 2.52  0.5 0.62
           0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \end{sparkline}.  You may want to clip them.  The starred version
  \verb|sparkline*| creates \emph{clipped} sparklines: the graphics
  outside the rectangle (0,0) -- (1,1) plus a thin border of the width
  \verb|\sparklineclipsep| is clipped: 
  \begin{sparkline*}{10}
    \sparkrectangle 0.3 0.8
    \sparkdot 0.5 0.62 blue
    \sparkdot 1 0.2 red
    \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 2.52  0.5 0.62
           0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \end{sparkline*}.  The first sparkline was created with
\begin{verbatim}
  \begin{sparkline}{10}
    \sparkrectangle 0.3 0.8
    \sparkdot 0.5 0.62 blue
    \sparkdot 1 0.2 red
    \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 2.52  0.5 0.62
           0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \end{sparkline}.
\end{verbatim}
The second sparkline was created with
\begin{verbatim}
  \begin{sparkline*}{10}
    \sparkrectangle 0.3 0.8
    \sparkdot 0.5 0.62 blue
    \sparkdot 1 0.2 red
    \spark 0.1 0.95  0.2 0.8  0.3 0.3  0.4 2.52  0.5 0.62
           0.6 0.7   0.7 0.5  0.8 0.4  0.9 0.25  1 0.2 /
  \end{sparkline*}.
\end{verbatim}

The clipping separation is set to 2~pt.  You can change it with
\begin{verbatim}
\setlength\sparklineclipsep{...}.
\end{verbatim}


\section*{Version history}
\begin{description}

  \item[] Dev 26, 2016

    version 1.7: Boris Veytsman (borisv@lk.net).  Added clipping,
    extensible bottom lines, some bug fixes. 

	\item[] Oct 19, 2014

	version 1.6: Emiel van Miltenburg (emiel.van.miltenburg@vu.nl) - Adding a bottom line (the x-axis, this is useful to visually separate different bar charts that are next to each other) and changing the color of the bottom line.

\item[] Nov 21, 2009

version 1.5: Benno Puetz (puetz@mpipsykl.mpg.de) made change of colors possible.

\item[] Apr 20, 2009

    version 1.4: Alexander Kowalski (Alexander.Kowarik@statistik.gv.at) found an error concerning spark-rectangles

\item[] Mar 21, 2007

    version 1.3: User adjustable colors and parameters added by Dan
    Luecking $\langle$luecking@uark.edu$\rangle$

\item[] Mar 19, 2007

    version 1.2: Sparkbars added thanks to Harlan Harris
    $\langle$harlan@harris.name$\rangle$

\item[] Apr 21, 2005

    version 1.1: bug removed thanks to Mathias Hofmann
    $\langle$mathias.hofmann@web.de$\rangle$

\item[] Dec 12, 2004

    version 1.0: first version of sparklines
\end{description}

\end{document}