Debian Codegraph @

texmf-dist/doc/generic/pgf/pgfmanual-en-tikz-plots.tex

raw
1 % Copyright 2019 by Till Tantau
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Free Documentation License.
7 %
8 % See the file doc/generic/pgf/licenses/LICENSE for more details.
9
10
11 \section{Plots of Functions}
12 \label{section-tikz-plots}
13
14 A warning before we get started: \emph{If you are looking for an easy way to
15 create a normal plot of a function with scientific axes, ignore this section
16 and instead look at the |pgfplots| package or at the |datavisualization|
17 command from Part~\ref{part-dv}.}
18
19
20 \subsection{Overview}
21 \label{section-why-pgname-for-plots}
22
23 \tikzname\ can be used to create plots of functions, a job that is normally
24 handled by powerful programs like \textsc{gnuplot} or \textsc{mathematica}.
25 These programs can produce two different kinds of output: First, they can
26 output a complete plot picture in a certain format (like \pdf) that includes
27 all low-level commands necessary for drawing the complete plot (including axes
28 and labels). Second, they can usually also produce ``just plain data'' in the
29 form of a long list of coordinates. Most of the powerful programs consider it a
30 to be ``a bit boring'' to just output tabled data and very much prefer to
31 produce fancy pictures. Nevertheless, when coaxed, they can also provide the
32 plain data.
33
34 The advantage of creating plots directly using \tikzname\ is
35 \emph{consistency:} Plots created using \tikzname\ will automatically have the
36 same styling and fonts as those used in the rest of a document -- something
37 that is hard to do right when an external program gets involved. Other problems
38 people encounter with external programs include: Formulas will look different,
39 if they can be rendered at all; line widths will usually be too thick or too
40 thin; scaling effects upon inclusion can create a mismatch between sizes in the
41 plot and sizes in the text; the automatic grid generated by most programs is
42 mostly distracting; the automatic ticks generated by most programs are cryptic
43 numerics (try adding a tick reading ``$\pi$'' at the right point); most
44 programs make it very easy to create ``chart junk'' in a most convenient
45 fashion; arrows and plot marks will almost never match the arrows used in the
46 rest of the document. This list is not exhaustive, unfortunately.
47
48 There are basically three ways of creating plots using \tikzname:
49 %
50 \begin{enumerate}
51 \item Use the |plot| path operation. How this works is explained in the
52 present section. This is the most ``basic'' of the three options and
53 forces you to do a lot of things ``by hand'' like adding axes or ticks.
54 \item Use the |datavisualization| path command, which is documented in
55 Part~\ref{part-dv}. This command is much more powerful than the |plot|
56 path operation and produces complete plots including axes and ticks.
57 The downside is that you cannot use it to ``just'' quickly plot a
58 simple curve (or, more precisely, it is hard to use it in this way).
59 \item Use the |pgfplots| package, which is basically an alternative to the
60 |datavisualization| command. While the underlying philosophy of this
61 package is not as ``ambitious'' as that of the command
62 |datavisualization|, it is somewhat more mature, has a simpler design,
63 and wider support base.
64 \end{enumerate}
65
66
67 \subsection{The Plot Path Operation}
68
69 The |plot| path operation can be used to append a line or curve to the path
70 that goes through a large number of coordinates. These coordinates are either
71 given in a simple list of coordinates, read from some file, or they are
72 computed on the fly.
73
74 The syntax of the |plot| comes in different versions.
75
76 \begin{pathoperation}{--plot}{\meta{further arguments}}
77 This operation plots the curve through the coordinates specified in the
78 \meta{further arguments}. The current (sub)path is simply continued, that
79 is, a line-to operation to the first point of the curve is implicitly
80 added. The details of the \meta{further arguments} will be explained in a
81 moment.
82 \end{pathoperation}
83
84 \begin{pathoperation}{plot}{\meta{further arguments}}
85 This operation plots the curve through the coordinates specified in the
86 \meta{further arguments} by first ``moving'' to the first coordinate of the
87 curve.
88 \end{pathoperation}
89
90 The \meta{further arguments} are used in different ways to specifying the
91 coordinates of the points to be plotted:
92 %
93 \begin{enumerate}
94 \item \opt{|--|}|plot|\oarg{local
95 options}\declare{|coordinates{|\meta{coordinate 1}\meta{coordinate
96 2}\dots\meta{coordinate $n$}|}|}
97 \item \opt{|--|}|plot|\oarg{local
98 options}\declare{|file{|\meta{filename}|}|}
99 \item \opt{|--|}|plot|\oarg{local options}\declare{\meta{coordinate
100 expression}}
101 \item \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot
102 formula}|}|}
103 \end{enumerate}
104
105 These different ways are explained in the following.
106
107
108 \subsection{Plotting Points Given Inline}
109
110 Points can be given directly in the \TeX-file as in the following example:
111 %
112 \begin{codeexample}[]
113 \tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)};
114 \end{codeexample}
115
116 Here is an example showing the difference between |plot| and |--plot|:
117 %
118 \begin{codeexample}[]
119 \begin{tikzpicture}
120 \draw (0,0) -- (1,1) plot coordinates {(2,0) (4,0)};
121 \draw[color=red,xshift=5cm]
122 (0,0) -- (1,1) -- plot coordinates {(2,0) (4,0)};
123 \end{tikzpicture}
124 \end{codeexample}
125
126
127 \subsection{Plotting Points Read From an External File}
128
129 The second way of specifying points is to put them in an external file named
130 \meta{filename}. Currently, the only file format that \tikzname\ allows is the
131 following: Each line of the \meta{filename} should contain one line starting
132 with two numbers, separated by a space. A line may also be empty or, if it
133 starts with |#| or |%| it is considered empty. For such lines, a ``new data
134 set'' is started, typically resulting in a new subpath being started in the
135 plot (see Section~\ref{section-plot-jumps} on how to change this behavior, if
136 necessary). For lines containing two numbers, they must be separated by a
137 space. They may be following by arbitrary text, which is ignored, \emph{except}
138 if it is |o| or |u|. In the first case, the point is considered to be an
139 \emph{outlier} and normally also results in a new subpath being started. In the
140 second case, the point is considered to be \emph{undefined}, which also results
141 in a new subpath being started. Again, see Section~\ref{section-plot-jumps} on
142 how to change this, if necessary. (This is exactly the format that
143 \textsc{gnuplot} produces when you say |set table|.)
144 %
145 \begin{codeexample}[]
146 \tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table};
147 \end{codeexample}
148
149 The file |plots/pgfmanual-sine.table| reads:
150 %
151 \begin{codeexample}[code only]
152 #Curve 0, 20 points
153 #x y type
154 0.00000 0.00000 i
155 0.52632 0.50235 i
156 1.05263 0.86873 i
157 1.57895 0.99997 i
158 ...
159 9.47368 -0.04889 i
160 10.00000 -0.54402 i
161 \end{codeexample}
162 %
163 It was produced from the following source, using |gnuplot|:
164 %
165 \begin{codeexample}[code only]
166 set table "../plots/pgfmanual-sine.table"
167 set format "%.5f"
168 set samples 20
169 plot [x=0:10] sin(x)
170 \end{codeexample}
171
172 The \meta{local options} of the |plot| operation are local to each plot and do
173 not affect other plots ``on the same path''. For example, |plot[yshift=1cm]|
174 will locally shift the plot 1cm upward. Remember, however, that most options
175 can only be applied to paths as a whole. For example, |plot[red]| does not have
176 the effect of making the plot red. After all, you are trying to ``locally''
177 make part of the path red, which is not possible.
178
179
180 \subsection{Plotting a Function}
181 \label{section-tikz-plot}
182
183 When you plot a function, the coordinates of the plot data can be computed by
184 evaluating a mathematical expression. Since \pgfname\ comes with a mathematical
185 engine, you can specify this expression and then have \tikzname\ produce the
186 desired coordinates for you, automatically.
187
188 Since this case is quite common when plotting a function, the syntax is easy:
189 Following the |plot| command and its local options, you directly provide a
190 \meta{coordinate expression}. It looks like a normal coordinate, but inside you
191 may use a special macro, which is |\x| by default, but this can be changed
192 using the |variable| option. The \meta{coordinate expression} is then evaluated
193 for different values for |\x| and the resulting coordinates are plotted.
194
195 Note that you will often have to put the $x$- or $y$-coordinate inside braces,
196 namely whenever you use an expression involving a parenthesis.
197
198 The following options influence how the \meta{coordinate expression} is
199 evaluated:
200 %
201 \begin{key}{/tikz/variable=\meta{macro} (initially \string\x)}
202 Sets the macro whose value is set to the different values when
203 \meta{coordinate expression} is evaluated.
204 \end{key}
205
206 \begin{key}{/tikz/samples=\meta{number} (initially 25)}
207 Sets the number of samples used in the plot.
208 \end{key}
209
210 \begin{key}{/tikz/domain=\meta{start}|:|\meta{end} (initially -5:5)}
211 Sets the domain from which the samples are taken.
212 \end{key}
213
214 \begin{key}{/tikz/samples at=\meta{sample list}}
215 This option specifies a list of positions for which the variable should be
216 evaluated. For instance, you can say |samples at={1,2,8,9,10}| to have the
217 variable evaluated exactly for values $1$, $2$, $8$, $9$, and $10$. You can
218 use the |\foreach| syntax, so you can use |...| inside the \meta{sample
219 list}.
220
221 When this option is used, the |samples| and |domain| option are overruled.
222 The other way round, setting either |samples| or |domain| will overrule
223 this option.
224 \end{key}
225 %
226 \begin{codeexample}[]
227 \begin{tikzpicture}[domain=0:4]
228 \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
229
230 \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
231 \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
232
233 \draw[color=red] plot (\x,\x) node[right] {$f(x) =x$};
234 % \x r means to convert '\x' from degrees to _r_adians:
235 \draw[color=blue] plot (\x,{sin(\x r)}) node[right] {$f(x) = \sin x$};
236 \draw[color=orange] plot (\x,{0.05*exp(\x)}) node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
237 \end{tikzpicture}
238 \end{codeexample}
239
240 \begin{codeexample}[]
241 \tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,variable=\t]
242 plot ({\t*sin(\t r)},{\t*cos(\t r)});
243 \end{codeexample}
244
245 \begin{codeexample}[]
246 \tikz \draw[domain=0:360,smooth,variable=\t]
247 plot ({sin(\t)},\t/360,{cos(\t)});
248 \end{codeexample}
249
250
251 \subsection{Plotting a Function Using Gnuplot}
252 \label{section-tikz-gnuplot}
253
254 Often, you will want to plot points that are given via a function like $f(x) =
255 x \sin x$. Unfortunately, \TeX\ does not really have enough computational power
256 to generate the points of such a function efficiently (it is a text processing
257 program, after all). However, if you allow it, \TeX\ can try to call external
258 programs that can easily produce the necessary points. Currently, \tikzname\
259 knows how to call \textsc{gnuplot}.
260
261 When \tikzname\ encounters your operation
262 |plot[id=|\meta{id}|] function{x*sin(x)}| for the first time, it will create a
263 file called \meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is
264 |\jobname.| by default, that is, the name of your main |.tex| file. If no
265 \meta{id} is given, it will be empty, which is alright, but it is better when
266 each plot has a unique \meta{id} for reasons explained in a moment. Next,
267 \tikzname\ writes some initialization code into this file followed by
268 |plot x*sin(x)|. The initialization code sets up things such that the |plot|
269 operation will write the coordinates into another file called
270 \meta{prefix}\meta{id}|.table|. Finally, this table file is read as if you had
271 said |plot file{|\meta{prefix}\meta{id}|.table}|.
272
273 For the plotting mechanism to work, two conditions must be met:
274 %
275 \begin{enumerate}
276 \item You must have allowed \TeX\ to call external programs. This is often
277 switched off by default since this is a security risk (you might,
278 without knowing, run a \TeX\ file that calls all sorts of ``bad''
279 commands). To enable this ``calling external programs'' a command line
280 option must be given to the \TeX\ program. Usually, it is called
281 something like |shell-escape| or |enable-write18|. For example, for my
282 |pdflatex| the option |--shell-escape| can be given.
283 \item You must have installed the |gnuplot| program and \TeX\ must find it
284 when compiling your file.
285 \end{enumerate}
286
287 Unfortunately, these conditions will not always be met. Especially if you pass
288 some source to a coauthor and the coauthor does not have \textsc{gnuplot}
289 installed, he or she will have trouble compiling your files.
290
291 For this reason, \tikzname\ behaves differently when you compile your graphic
292 for the second time: If upon reaching |plot[id=|\meta{id}|] function{...}| the
293 file \meta{prefix}\meta{id}|.table| already exists \emph{and} if the
294 \meta{prefix}\meta{id}|.gnuplot| file contains what \tikzname\ thinks that it
295 ``should'' contain, the |.table| file is immediately read without trying to
296 call a |gnuplot| program. This approach has the following advantages:
297 %
298 \begin{enumerate}
299 \item If you pass a bundle of your |.tex| file and all |.gnuplot| and
300 |.table| files to someone else, that person can \TeX\ the |.tex| file
301 without having to have |gnuplot| installed.
302 \item If the |\write18| feature is switched off for security reasons (a
303 good idea), then, upon the first compilation of the |.tex| file, the
304 |.gnuplot| will still be generated, but not the |.table| file. You can
305 then simply call |gnuplot| ``by hand'' for each |.gnuplot| file, which
306 will produce all necessary |.table| files.
307 \item If you change the function that you wish to plot or its domain,
308 \tikzname\ will automatically try to regenerate the |.table| file.
309 \item If, out of laziness, you do not provide an |id|, the same |.gnuplot|
310 will be used for different plots, but this is not a problem since the
311 |.table| will automatically be regenerated for each plot on-the-fly.
312 \emph{Note: If you intend to share your files with someone else, always
313 use an id, so that the file can by typeset without having
314 \textsc{gnuplot} installed.} Also, having unique ids for each plot will
315 improve compilation speed since no external programs need to be called,
316 unless it is really necessary.
317 \end{enumerate}
318
319 When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot
320 formula} must be given in the |gnuplot| syntax, whose details are beyond the
321 scope of this manual. Here is the ultra-condensed essence: Use |x| as the
322 variable and use the C-syntax for normal plots, use |t| as the variable for
323 parametric plots. Here are some examples:
324 %
325 \begin{codeexample}[]
326 \begin{tikzpicture}[domain=0:4]
327 \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
328
329 \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
330 \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
331
332 \draw[color=red] plot[id=x] function{x} node[right] {$f(x) =x$};
333 \draw[color=blue] plot[id=sin] function{sin(x)} node[right] {$f(x) = \sin x$};
334 \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
335 \end{tikzpicture}
336 \end{codeexample}
337
338 The plot is influenced by the following options: First, the options |samples|
339 and |domain| explained earlier. Second, there are some more specialized
340 options.
341
342 \begin{key}{/tikz/parametric=\meta{boolean} (default true)}
343 Sets whether the plot is a parametric plot. If true, then |t| must be used
344 instead of |x| as the parameter and two comma-separated functions must be
345 given in the \meta{gnuplot formula}. An example is the following:
346 %
347 \begin{codeexample}[]
348 \tikz \draw[scale=0.5,domain=-3.141:3.141,smooth]
349 plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)};
350 \end{codeexample}
351 %
352 \end{key}
353
354 \begin{key}{/tikz/range=\meta{start}|:|\meta{end}}
355 This key sets the range of the plot. If set, all points whose
356 $y$-coordinates lie outside this range will be considered to be outliers
357 and will cause jumps in the plot, by default:
358 %
359 \begin{codeexample}[]
360 \tikz \draw[scale=0.5,domain=-3.141:3.141, samples=100, smooth, range=-3:3]
361 plot[id=tan-example] function{tan(x)};
362 \end{codeexample}
363 %
364 \end{key}
365
366 \begin{key}{/tikz/yrange=\meta{start}|:|\meta{end}}
367 Same as |range|.
368 \end{key}
369
370 \begin{key}{/tikz/xrange=\meta{start}|:|\meta{end}}
371 Set the $x$-range. This makes sense only for parametric plots.
372 %
373 \begin{codeexample}[]
374 \tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,xrange=0:1]
375 plot[parametric,id=parametric-example-cut] function{t*sin(t),t*cos(t)};
376 \end{codeexample}
377 %
378 \end{key}
379
380 \begin{key}{/tikz/id=\meta{id}}
381 Sets the identifier of the current plot. This should be a unique identifier
382 for each plot (though things will also work if it is not, but not as well,
383 see the explanations above). The \meta{id} will be part of a filename, so
384 it should not contain anything fancy like |*| or |$|.%$
385 \end{key}
386
387 \begin{key}{/tikz/prefix=\meta{prefix}}
388 The \meta{prefix} is put before each plot file name. The default is
389 |\jobname.|, but if you have many plots, it might be better to use, say
390 |plots/| and have all plots placed in a directory. You have to create the
391 directory yourself.
392 \end{key}
393
394 \begin{key}{/tikz/raw gnuplot}
395 This key causes the \meta{gnuplot formula} to be passed on to
396 \textsc{gnuplot} without setting up the samples or the |plot| operation.
397 Thus, you could write
398 %
399 \begin{codeexample}[code only]
400 plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)}
401 \end{codeexample}
402 %
403 This can be useful for complicated things that need to be passed to
404 \textsc{gnuplot}. However, for really complicated situations you should
405 create a special external generating \textsc{gnuplot} file and use the
406 |file|-syntax to include the table ``by hand''.
407 \end{key}
408
409 The following styles influence the plot:
410 %
411 \begin{stylekey}{/tikz/every plot (initially \normalfont empty)}
412 This style is installed in each plot, that is, as if you always said
413 %
414 \begin{codeexample}[code only]
415 plot[every plot,...]
416 \end{codeexample}
417 %
418 This is most useful for globally setting a prefix for all plots by saying:
419 %
420 \begin{codeexample}[code only]
421 \tikzset{every plot/.style={prefix=plots/}}
422 \end{codeexample}
423 %
424 \end{stylekey}
425
426
427 \subsection{Placing Marks on the Plot}
428
429 As we saw already, it is possible to add \emph{marks} to a plot using the
430 |mark| option. When this option is used, a copy of the plot mark is placed on
431 each point of the plot. Note that the marks are placed \emph{after} the whole
432 path has been drawn/filled/shaded. In this respect, they are handled like text
433 nodes.
434
435 In detail, the following options govern how marks are drawn:
436 %
437 \begin{key}{/tikz/mark=\meta{mark mnemonic}}
438 Sets the mark to a mnemonic that has previously been defined using the
439 |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available, which
440 draw a filled circle, a plus, and a cross as marks. Many more marks become
441 available when the library |plotmarks| is loaded.
442 Section~\ref{section-plot-marks} lists the available plot marks.
443
444 One plot mark is special: the |ball| plot mark is available only in
445 \tikzname. The |ball color| option determines the balls's color. Do not use
446 this option with a large number of marks since it will take very long to
447 render in PostScript.
448
449 \begin{tabular}{lc}
450 Option & Effect \\
451 \hline
452 \vrule height14pt width0pt \plotmarkentrytikz{ball}
453 \end{tabular}
454 \end{key}
455
456 \begin{key}{/tikz/mark repeat=\meta{r}}
457 This option tells \tikzname\ that only every $r$th mark should be drawn.
458 %
459 \begin{codeexample}[]
460 \tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table};
461 \end{codeexample}
462 %
463 \end{key}
464
465 \begin{key}{/tikz/mark phase=\meta{p}}
466 This option tells \tikzname\ that the first mark to be draw should be the
467 $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on.
468 %
469 \begin{codeexample}[]
470 \tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table};
471 \end{codeexample}
472 %
473 \end{key}
474
475 \begin{key}{/tikz/mark indices=\meta{list}}
476 This option allows you to specify explicitly the indices at which a mark
477 should be placed. Counting starts with 1. You can use the |\foreach|
478 syntax, that is, |...| can be used.
479 %
480 \begin{codeexample}[]
481 \tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth]
482 file {plots/pgfmanual-sine.table};
483 \end{codeexample}
484 %
485 \end{key}
486
487 \begin{key}{/tikz/mark size=\meta{dimension}}
488 Sets the size of the plot marks. For circular plot marks, \meta{dimension}
489 is the radius, for other plot marks \meta{dimension} should be about half
490 the width and height.
491
492 This option is not really necessary, since you achieve the same effect by
493 specifying |scale=|\meta{factor} as a local option, where \meta{factor} is
494 the quotient of the desired size and the default size. However, using
495 |mark size| is a bit faster and more natural.
496 \end{key}
497
498 \begin{stylekey}{/tikz/every mark}
499 This style is installed before drawing plot marks. For example, you can
500 scale (or otherwise transform) the plot mark or set its color.
501 \end{stylekey}
502
503 \begin{key}{/tikz/mark options=\meta{options}}
504 Redefines |every mark| such that it sets \marg{options}.
505 %
506 \begin{codeexample}[]
507 \tikz \fill[fill=blue!20]
508 plot[mark=triangle*,mark options={color=blue,rotate=180}]
509 file{plots/pgfmanual-sine.table} |- (0,0);
510 \end{codeexample}
511 %
512 \end{key}
513
514 \begin{stylekey}{/tikz/no marks}
515 Disables markers (the same as |mark=none|).
516 \end{stylekey}
517 %
518 \begin{stylekey}{/tikz/no markers}
519 Disables markers (the same as |mark=none|).
520 \end{stylekey}
521
522
523 \subsection{Smooth Plots, Sharp Plots, Jump Plots, Comb Plots and Bar Plots}
524
525 There are different things the |plot| operation can do with the points it reads
526 from a file or from the inlined list of points. By default, it will connect
527 these points by straight lines. However, you can also use options to change the
528 behavior of |plot|.
529
530 \begin{key}{/tikz/sharp plot}
531 This is the default and causes the points to be connected by straight
532 lines. This option is included only so that you can ``switch back'' if you
533 ``globally'' install, say, |smooth|.
534 \end{key}
535
536 \begin{key}{/tikz/smooth}
537 This option causes the points on the path to be connected using a smooth
538 curve:
539 %
540 \begin{codeexample}[]
541 \tikz\draw plot[smooth] file{plots/pgfmanual-sine.table};
542 \end{codeexample}
543
544 Note that the smoothing algorithm is not very intelligent. You will get the
545 best results if the bending angles are small, that is, less than about
546 $30^\circ$ and, even more importantly, if the distances between points are
547 about the same all over the plotting path.
548 \end{key}
549
550 \begin{key}{/tikz/tension=\meta{value}}
551 This option influences how ``tight'' the smoothing is. A lower value will
552 result in sharper corners, a higher value in more ``round'' curves. A value
553 of $1$ results in a circle if four points at quarter-positions on a circle
554 are given. The default is $0.55$. The ``correct'' value depends on the
555 details of plot.
556 %
557 \begin{codeexample}[]
558 \begin{tikzpicture}[smooth cycle]
559 \draw plot[tension=0.2]
560 coordinates{(0,0) (1,1) (2,0) (1,-1)};
561 \draw[yshift=-2.25cm] plot[tension=0.5]
562 coordinates{(0,0) (1,1) (2,0) (1,-1)};
563 \draw[yshift=-4.5cm] plot[tension=1]
564 coordinates{(0,0) (1,1) (2,0) (1,-1)};
565 \end{tikzpicture}
566 \end{codeexample}
567 %
568 \end{key}
569
570 \begin{key}{/tikz/smooth cycle}
571 This option causes the points on the path to be connected using a closed
572 smooth curve.
573 %
574 \begin{codeexample}[]
575 \tikz[scale=0.5]
576 \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)}
577 plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle;
578 \end{codeexample}
579 %
580 \end{key}
581
582 \begin{key}{/tikz/const plot}
583 This option causes the points on the path to be connected using piecewise
584 constant series of lines:
585 %
586 \begin{codeexample}[]
587 \tikz\draw plot[const plot] file{plots/pgfmanual-sine.table};
588 \end{codeexample}
589 %
590 \end{key}
591
592 \begin{key}{/tikz/const plot mark left}
593 Just an alias for |/tikz/const plot|.
594 %
595 \begin{codeexample}[]
596 \tikz\draw plot[const plot mark left,mark=*] file{plots/pgfmanual-sine.table};
597 \end{codeexample}
598 %
599 \end{key}
600
601 \begin{key}{/tikz/const plot mark right}
602 A variant of |/tikz/const plot| which places its mark on the right ends:
603 %
604 \begin{codeexample}[]
605 \tikz\draw plot[const plot mark right,mark=*] file{plots/pgfmanual-sine.table};
606 \end{codeexample}
607 %
608 \end{key}
609
610 \begin{key}{/tikz/const plot mark mid}
611 A variant of |/tikz/const plot| which places its mark in the middle of the
612 horizontal lines:
613 %
614 \begin{codeexample}[]
615 \tikz\draw plot[const plot mark mid,mark=*] file{plots/pgfmanual-sine.table};
616 \end{codeexample}
617 %
618 More precisely, it generates vertical lines in the middle between each pair
619 of consecutive points. If the mesh width is constant, this leads to
620 symmetrically placed marks (``middle'').
621 \end{key}
622
623 \begin{key}{/tikz/jump mark left}
624 This option causes the points on the path to be drawn using piecewise
625 constant, non-connected series of lines. If there are any marks, they will
626 be placed on left open ends:
627 %
628 \begin{codeexample}[]
629 \tikz\draw plot[jump mark left, mark=*] file{plots/pgfmanual-sine.table};
630 \end{codeexample}
631 %
632 \end{key}
633
634 \begin{key}{/tikz/jump mark right}
635 This option causes the points on the path to be drawn using piecewise
636 constant, non-connected series of lines. If there are any marks, they will
637 be placed on right open ends:
638 %
639 \begin{codeexample}[]
640 \tikz\draw plot[jump mark right, mark=*] file{plots/pgfmanual-sine.table};
641 \end{codeexample}
642 %
643 \end{key}
644
645 \begin{key}{/tikz/jump mark mid}
646 This option causes the points on the path to be drawn using piecewise
647 constant, non-connected series of lines. If there are any marks, they will
648 be placed in the middle of the horizontal line segments:
649 %
650 \begin{codeexample}[]
651 \tikz\draw plot[jump mark mid, mark=*] file{plots/pgfmanual-sine.table};
652 \end{codeexample}
653
654 In case of non-constant mesh widths, the same remarks as for
655 |const plot mark mid| apply.
656 \end{key}
657
658 \begin{key}{/tikz/ycomb}
659 This option causes the |plot| operation to interpret the plotting points
660 differently. Instead of connecting them, for each point of the plot a
661 straight line is added to the path from the $x$-axis to the point,
662 resulting in a sort of ``comb'' or ``bar diagram''.
663 %
664 \begin{codeexample}[]
665 \tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table};
666 \end{codeexample}
667
668 \begin{codeexample}[]
669 \begin{tikzpicture}[ycomb]
670 \draw[color=red,line width=6pt]
671 plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
672 \draw[color=red!50,line width=4pt,xshift=3pt]
673 plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
674 \end{tikzpicture}
675 \end{codeexample}
676 %
677 \end{key}
678
679 \begin{key}{/tikz/xcomb}
680 This option works like |ycomb| except that the bars are horizontal.
681 %
682 \begin{codeexample}[]
683 \tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)};
684 \end{codeexample}
685 %
686 \end{key}
687
688 \begin{key}{/tikz/polar comb}
689 This option causes a line from the origin to the point to be added to the
690 path for each plot point.
691 %
692 \begin{codeexample}[]
693 \tikz \draw plot[polar comb,
694 mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt]
695 coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)};
696 \end{codeexample}
697 %
698 \end{key}
699
700 \begin{key}{/tikz/ybar}
701 This option produces fillable bar plots. It is thus very similar to
702 |ycomb|, but it employs rectangular shapes instead of line-to operations.
703 It thus allows to use any fill or pattern style.
704 %
705 \begin{codeexample}[]
706 \tikz\draw[draw=blue,fill=blue!60!black] plot[ybar] file{plots/pgfmanual-sine.table};
707 \end{codeexample}
708
709 \begin{codeexample}[]
710 \begin{tikzpicture}[ybar]
711 \draw[color=red,fill=red!80,bar width=6pt]
712 plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
713 \draw[color=red!50,fill=red!20,bar width=4pt,bar shift=3pt]
714 plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
715 \end{tikzpicture}
716 \end{codeexample}
717 %
718 The use of |bar width| and |bar shift| is explained in the |plothandlers|
719 library documentation, section~\ref{section-plotlib-bar-handlers}. Please
720 refer to page~\pageref{key-bar-width}.
721 \end{key}
722
723 \begin{key}{/tikz/xbar}
724 This option works like |ybar| except that the bars are horizontal.
725 %
726 \begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
727 \tikz \draw[pattern=north west lines] plot[xbar]
728 coordinates{(1,0) (0.4,1) (1.7,2) (1.6,3)};
729 \end{codeexample}
730 %
731 \end{key}
732
733 \begin{key}{/tikz/ybar interval}
734 As |/tikz/ybar|, this options produces vertical bars. However, bars are
735 centered at coordinate \emph{intervals} instead of interval edges, and the
736 bar's width is also determined relatively to the interval's length:
737 %
738 \begin{codeexample}[]
739 \begin{tikzpicture}[ybar interval,x=10pt]
740 \draw[color=red,fill=red!80]
741 plot coordinates{(0,2) (2,1.2) (3,.3) (5,1.7) (8,.9) (9,.9)};
742 \end{tikzpicture}
743 \end{codeexample}
744 %
745 Since there are $N$ intervals $[x_i,x_{i+1}]$ for given $N+1$ coordinates,
746 you will always have one coordinate more than bars. The last $y$ value will
747 be ignored.
748
749 You can configure relative shifts and relative bar widths, which is
750 explained in the |plothandlers| library documentation,
751 section~\ref{section-plotlib-bar-handlers}. Please refer to
752 page~\pageref{key-bar-interval-width}.
753 \end{key}
754
755 \begin{key}{/tikz/xbar interval}
756 Works like |ybar interval|, but for horizontal bar plots.
757 %
758 \begin{codeexample}[]
759 \begin{tikzpicture}[xbar interval,x=0.5cm,y=0.5cm]
760 \draw[color=red,fill=red!80]
761 plot coordinates {(3,0) (2,1) (4,1.5) (1,4) (2,6) (2,7)};
762 \end{tikzpicture}
763 \end{codeexample}
764 %
765 \end{key}
766
767 \begin{key}{/tikz/only marks}
768 This option causes only marks to be shown; no path segments are added to
769 the actual path. This can be useful for quickly adding some marks to a
770 path.
771 %
772 \begin{codeexample}[]
773 \tikz \draw (0,0) sin (1,1) cos (2,0)
774 plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)};
775 \end{codeexample}
776 \end{key}