summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-plots.tex
blob: 203689729f1c62f1ca46b32a8b415857a273fc44 (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
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
% Copyright 2019 by Till Tantau
%
% This file may be distributed and/or modified
%
% 1. under the LaTeX Project Public License and/or
% 2. under the GNU Free Documentation License.
%
% See the file doc/generic/pgf/licenses/LICENSE for more details.


\section{Plots of Functions}
\label{section-tikz-plots}

A warning before we get started: \emph{If you are looking for an easy way to
create a normal plot of a function with scientific axes, ignore this section
and instead look at the |pgfplots| package or at the |datavisualization|
command from Part~\ref{part-dv}.}


\subsection{Overview}
\label{section-why-pgname-for-plots}

\tikzname\ can be used to create plots of functions, a job that is normally
handled by powerful programs like \textsc{gnuplot} or \textsc{mathematica}.
These programs can produce two different kinds of output: First, they can
output a complete plot picture in a certain format (like \pdf) that includes
all low-level commands necessary for drawing the complete plot (including axes
and labels). Second, they can usually also produce ``just plain data'' in the
form of a long list of coordinates. Most of the powerful programs consider it a
to be ``a bit boring'' to just output tabled data and very much prefer to
produce fancy pictures. Nevertheless, when coaxed, they can also provide the
plain data.

The advantage of creating plots directly using \tikzname\ is
\emph{consistency:} Plots created using \tikzname\ will automatically have the
same styling and fonts as those used in the rest of a document -- something
that is hard to do right when an external program gets involved. Other problems
people encounter with external programs include: Formulas will look different,
if they can be rendered at all; line widths will usually be too thick or too
thin; scaling effects upon inclusion can create a mismatch between sizes in the
plot and sizes in the text; the automatic grid generated by most programs is
mostly distracting; the automatic ticks generated by most programs are cryptic
numerics (try adding a tick reading ``$\pi$'' at the right point); most
programs make it very easy to create ``chart junk'' in a most convenient
fashion; arrows and plot marks will almost never match the arrows used in the
rest of the document. This list is not exhaustive, unfortunately.

There are basically three ways of creating plots using \tikzname:
%
\begin{enumerate}
    \item Use the |plot| path operation. How this works is explained in the
        present section. This is the most ``basic'' of the three options and
        forces you to do a lot of things ``by hand'' like adding axes or ticks.
    \item Use the |datavisualization| path command, which is documented in
        Part~\ref{part-dv}. This command is much more powerful than the |plot|
        path operation and produces complete plots including axes and ticks.
        The downside is that you cannot use it to ``just'' quickly plot a
        simple curve (or, more precisely, it is hard to use it in this way).
    \item Use the |pgfplots| package, which is basically an alternative to the
        |datavisualization| command. While the underlying philosophy of this
        package is not as ``ambitious'' as that of the command
        |datavisualization|, it is somewhat more mature, has a simpler design,
        and wider support base.
\end{enumerate}


\subsection{The Plot Path Operation}

The |plot| path operation can be used to append a line or curve to the path
that goes through a large number of coordinates. These coordinates are either
given in a simple list of coordinates, read from some file, or they are
computed on the fly.

The syntax of the |plot| comes in different versions.

\begin{pathoperation}{--plot}{\meta{further arguments}}
    This operation plots the curve through the coordinates specified in the
    \meta{further arguments}. The current (sub)path is simply continued, that
    is, a line-to operation to the first point of the curve is implicitly
    added. The details of the \meta{further arguments} will be explained in a
    moment.
\end{pathoperation}

\begin{pathoperation}{plot}{\meta{further arguments}}
    This operation plots the curve through the coordinates specified in the
    \meta{further arguments} by first ``moving'' to the first coordinate of the
    curve.
\end{pathoperation}

The \meta{further arguments} are used in different ways to specifying the
coordinates of the points to be plotted:
%
\begin{enumerate}
    \item \opt{|--|}|plot|\oarg{local
        options}\declare{|coordinates{|\meta{coordinate 1}\meta{coordinate
        2}\dots\meta{coordinate $n$}|}|}
    \item \opt{|--|}|plot|\oarg{local
        options}\declare{|file{|\meta{filename}|}|}
    \item \opt{|--|}|plot|\oarg{local options}\declare{\meta{coordinate
        expression}}
    \item \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot
        formula}|}|}
\end{enumerate}

These different ways are explained in the following.


\subsection{Plotting Points Given Inline}

Points can be given directly in the \TeX-file as in the following example:
%
\begin{codeexample}[]
\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)};
\end{codeexample}

Here is an example showing the difference between |plot| and |--plot|:
%
\begin{codeexample}[]
\begin{tikzpicture}
  \draw (0,0) -- (1,1) plot coordinates {(2,0)  (4,0)};
  \draw[color=red,xshift=5cm]
        (0,0) -- (1,1) -- plot coordinates {(2,0)  (4,0)};
\end{tikzpicture}
\end{codeexample}


\subsection{Plotting Points Read From an External File}

The second way of specifying points is to put them in an external file named
\meta{filename}. Currently, the only file format that \tikzname\ allows is the
following: Each line of the \meta{filename} should contain one line starting
with two numbers, separated by a space. A line may also be empty or, if it
starts with |#| or |%| it is considered empty. For such lines, a ``new data
set'' is started, typically resulting in a new subpath being started in the
plot (see Section~\ref{section-plot-jumps} on how to change this behavior, if
necessary). For lines containing two numbers, they must be separated by a
space. They may be following by arbitrary text, which is ignored, \emph{except}
if it is |o| or |u|. In the first case, the point is considered to be an
\emph{outlier} and normally also results in a new subpath being started. In the
second case, the point is considered to be \emph{undefined}, which also results
in a new subpath being started. Again, see Section~\ref{section-plot-jumps} on
how to change this, if necessary. (This is exactly the format that
\textsc{gnuplot} produces when you say |set terminal table|.)
%
\begin{codeexample}[]
\tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table};
\end{codeexample}

The file |plots/pgfmanual-sine.table| reads:
%
\begin{codeexample}[code only]
#Curve 0, 20 points
#x y type
0.00000 0.00000  i
0.52632 0.50235  i
1.05263 0.86873  i
1.57895 0.99997  i
...
9.47368 -0.04889  i
10.00000 -0.54402  i
\end{codeexample}
%
It was produced from the following source, using |gnuplot|:
%
\begin{codeexample}[code only]
set table  "../plots/pgfmanual-sine.table"
set format "%.5f"
set samples 20
plot [x=0:10] sin(x)
\end{codeexample}

The \meta{local options} of the |plot| operation are local to each plot and do
not affect other plots ``on the same path''. For example, |plot[yshift=1cm]|
will locally shift the plot 1cm upward. Remember, however, that most options
can only be applied to paths as a whole. For example, |plot[red]| does not have
the effect of making the plot red. After all, you are trying to ``locally''
make part of the path red, which is not possible.


\subsection{Plotting a Function}
\label{section-tikz-plot}

When you plot a function, the coordinates of the plot data can be computed by
evaluating a mathematical expression. Since \pgfname\ comes with a mathematical
engine, you can specify this expression and then have \tikzname\ produce the
desired coordinates for you, automatically.

Since this case is quite common when plotting a function, the syntax is easy:
Following the |plot| command and its local options, you directly provide a
\meta{coordinate expression}. It looks like a normal coordinate, but inside you
may use a special macro, which is |\x| by default, but this can be changed
using the |variable| option. The \meta{coordinate expression} is then evaluated
for different values for |\x| and the resulting coordinates are plotted.

Note that you will often have to put the $x$- or $y$-coordinate inside braces,
namely whenever you use an expression involving a parenthesis.

The following options influence how the \meta{coordinate expression} is
evaluated:
%
\begin{key}{/tikz/variable=\meta{macro} (initially x)}
    Sets the macro whose value is set to the different values when
    \meta{coordinate expression} is evaluated.
\end{key}

\begin{key}{/tikz/samples=\meta{number} (initially 25)}
    Sets the number of samples used in the plot.
\end{key}

\begin{key}{/tikz/domain=\meta{start}|:|\meta{end} (initially -5:5)}
    Sets the domain from which the samples are taken.
\end{key}

\begin{key}{/tikz/samples at=\meta{sample list}}
    This option specifies a list of positions for which the variable should be
    evaluated. For instance, you can say |samples at={1,2,8,9,10}| to have the
    variable evaluated exactly for values $1$, $2$, $8$, $9$, and $10$. You can
    use the |\foreach| syntax, so you can use |...| inside the \meta{sample
    list}.

    When this option is used, the |samples| and |domain| option are overruled.
    The other way round, setting either |samples| or |domain| will overrule
    this option.
\end{key}
%
\begin{codeexample}[]
\begin{tikzpicture}[domain=0:4]
  \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);

  \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
  \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};

  \draw[color=red]    plot (\x,\x)             node[right] {$f(x) =x$};
  % \x r means to convert '\x' from degrees to _r_adians:
  \draw[color=blue]   plot (\x,{sin(\x r)})    node[right] {$f(x) = \sin x$};
  \draw[color=orange] plot (\x,{0.05*exp(\x)}) node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,variable=\t]
  plot ({\t*sin(\t r)},{\t*cos(\t r)});
\end{codeexample}

\begin{codeexample}[]
\tikz \draw[domain=0:360,smooth,variable=\t]
  plot ({sin(\t)},\t/360,{cos(\t)});
\end{codeexample}


\subsection{Plotting a Function Using Gnuplot}
\label{section-tikz-gnuplot}

Often, you will want to plot points that are given via a function like $f(x) =
x \sin x$. Unfortunately, \TeX\ does not really have enough computational power
to generate the points of such a function efficiently (it is a text processing
program, after all). However, if you allow it, \TeX\ can try to call external
programs that can easily produce the necessary points. Currently, \tikzname\
knows how to call \textsc{gnuplot}.

When \tikzname\ encounters your operation
|plot[id=|\meta{id}|] function{x*sin(x)}| for the first time, it will create a
file called \meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is
|\jobname.| by default, that is, the name of your main |.tex| file. If no
\meta{id} is given, it will be empty, which is alright, but it is better when
each plot has a unique \meta{id} for reasons explained in a moment. Next,
\tikzname\ writes some initialization code into this file followed by
|plot x*sin(x)|. The initialization code sets up things such that the |plot|
operation will write the coordinates into another file called
\meta{prefix}\meta{id}|.table|. Finally, this table file is read as if you had
said |plot file{|\meta{prefix}\meta{id}|.table}|.

For the plotting mechanism to work, two conditions must be met:
%
\begin{enumerate}
    \item You must have allowed \TeX\ to call external programs. This is often
        switched off by default since this is a security risk (you might,
        without knowing, run a \TeX\ file that calls all sorts of ``bad''
        commands). To enable this ``calling external programs'' a command line
        option must be given to the \TeX\ program. Usually, it is called
        something like |shell-escape| or |enable-write18|. For example, for my
        |pdflatex| the option |--shell-escape| can be given.
    \item You must have installed the |gnuplot| program and \TeX\ must find it
        when compiling your file.
\end{enumerate}

Unfortunately, these conditions will not always be met. Especially if you pass
some source to a coauthor and the coauthor does not have \textsc{gnuplot}
installed, he or she will have trouble compiling your files.

For this reason, \tikzname\ behaves differently when you compile your graphic
for the second time: If upon reaching |plot[id=|\meta{id}|] function{...}| the
file \meta{prefix}\meta{id}|.table| already exists \emph{and} if the
\meta{prefix}\meta{id}|.gnuplot| file contains what \tikzname\ thinks that it
``should'' contain, the |.table| file is immediately read without trying to
call a |gnuplot| program. This approach has the following advantages:
%
\begin{enumerate}
    \item If you pass a bundle of your |.tex| file and all |.gnuplot| and
        |.table| files to someone else, that person can \TeX\ the |.tex| file
        without having to have |gnuplot| installed.
    \item If the |\write18| feature is switched off for security reasons (a
        good idea), then, upon the first compilation of the |.tex| file, the
        |.gnuplot| will still be generated, but not the |.table| file. You can
        then simply call |gnuplot| ``by hand'' for each |.gnuplot| file, which
        will produce all necessary |.table| files.
    \item If you change the function that you wish to plot or its domain,
        \tikzname\ will automatically try to regenerate the |.table| file.
    \item If, out of laziness, you do not provide an |id|, the same |.gnuplot|
        will be used for different plots, but this is not a problem since the
        |.table| will automatically be regenerated for each plot on-the-fly.
        \emph{Note: If you intend to share your files with someone else, always
        use an id, so that the file can by typeset without having
        \textsc{gnuplot} installed.} Also, having unique ids for each plot will
        improve compilation speed since no external programs need to be called,
        unless it is really necessary.
\end{enumerate}

When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot
formula} must be given in the |gnuplot| syntax, whose details are beyond the
scope of this manual. Here is the ultra-condensed essence: Use |x| as the
variable and use the C-syntax for normal plots, use |t| as the variable for
parametric plots. Here are some examples:
%
\begin{codeexample}[]
\begin{tikzpicture}[domain=0:4]
  \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);

  \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
  \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};

  \draw[color=red]    plot[id=x]   function{x}           node[right] {$f(x) =x$};
  \draw[color=blue]   plot[id=sin] function{sin(x)}      node[right] {$f(x) = \sin x$};
  \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
\end{tikzpicture}
\end{codeexample}

The plot is influenced by the following options: First, the options |samples|
and |domain| explained earlier. Second, there are some more specialized
options.

\begin{key}{/tikz/parametric=\meta{boolean} (default true)}
    Sets whether the plot is a parametric plot. If true, then |t| must be used
    instead of |x| as the parameter and two comma-separated functions must be
    given in the \meta{gnuplot formula}. An example is the following:
    %
\begin{codeexample}[]
\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth]
  plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/range=\meta{start}|:|\meta{end}}
    This key sets the range of the plot. If set, all points whose
    $y$-coordinates lie outside this range will be considered to be outliers
    and will cause jumps in the plot, by default:
    %
\begin{codeexample}[]
\tikz \draw[scale=0.5,domain=-3.141:3.141, samples=100, smooth, range=-3:3]
  plot[id=tan-example] function{tan(x)};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/yrange=\meta{start}|:|\meta{end}}
    Same as |range|.
\end{key}

\begin{key}{/tikz/xrange=\meta{start}|:|\meta{end}}
    Set the $x$-range. This makes sense only for parametric plots.
    %
\begin{codeexample}[]
\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,xrange=0:1]
  plot[parametric,id=parametric-example-cut] function{t*sin(t),t*cos(t)};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/id=\meta{id}}
    Sets the identifier of the current plot. This should be a unique identifier
    for each plot (though things will also work if it is not, but not as well,
    see the explanations above). The \meta{id} will be part of a filename, so
    it should not contain anything fancy like |*| or |$|.%$
\end{key}

\begin{key}{/tikz/prefix=\meta{prefix}}
    The \meta{prefix} is put before each plot file name. The default is
    |\jobname.|, but if you have many plots, it might be better to use, say
    |plots/| and have all plots placed in a directory. You have to create the
    directory yourself.
\end{key}

\begin{key}{/tikz/raw gnuplot}
    This key causes the \meta{gnuplot formula} to be passed on to
    \textsc{gnuplot} without setting up the samples or the |plot| operation.
    Thus, you could write
    %
\begin{codeexample}[code only]
plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)}
\end{codeexample}
    %
    This can be useful for complicated things that need to be passed to
    \textsc{gnuplot}. However, for really complicated situations you should
    create a special external generating \textsc{gnuplot} file and use the
    |file|-syntax to include the table ``by hand''.
\end{key}

The following styles influence the plot:
%
\begin{stylekey}{/tikz/every plot (initially \normalfont empty)}
    This style is installed in each plot, that is, as if you always said
    %
\begin{codeexample}[code only]
  plot[every plot,...]
\end{codeexample}
    %
    This is most useful for globally setting a prefix for all plots by saying:
    %
\begin{codeexample}[code only]
\tikzset{every plot/.style={prefix=plots/}}
\end{codeexample}
    %
\end{stylekey}


\subsection{Placing Marks on the Plot}

As we saw already, it is possible to add \emph{marks} to a plot using the
|mark| option. When this option is used, a copy of the plot mark is placed on
each point of the plot. Note that the marks are placed \emph{after} the whole
path has been drawn/filled/shaded. In this respect, they are handled like text
nodes.

In detail, the following options govern how marks are drawn:
%
\begin{key}{/tikz/mark=\meta{mark mnemonic}}
    Sets the mark to a mnemonic that has previously been defined using the
    |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available, which
    draw a filled circle, a plus, and a cross as marks. Many more marks become
    available when the library |plotmarks| is loaded.
    Section~\ref{section-plot-marks} lists the available plot marks.

    One plot mark is special: the |ball| plot mark is available only in
    \tikzname. The |ball color| option determines the balls's color. Do not use
    this option with a large number of marks since it will take very long to
    render in PostScript.

    \begin{tabular}{lc}
        Option & Effect \\
            \hline
        \vrule height14pt width0pt \plotmarkentrytikz{ball}
    \end{tabular}
\end{key}

\begin{key}{/tikz/mark repeat=\meta{r}}
    This option tells \tikzname\ that only every $r$th mark should be drawn.
    %
\begin{codeexample}[]
\tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/mark phase=\meta{p}}
    This option tells \tikzname\ that the first mark to be draw should be the
    $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on.
    %
\begin{codeexample}[]
\tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/mark indices=\meta{list}}
    This option allows you to specify explicitly the indices at which a mark
    should be placed. Counting starts with 1. You can use the |\foreach|
    syntax, that is, |...| can be used.
    %
\begin{codeexample}[]
\tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth]
  file {plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/mark size=\meta{dimension}}
    Sets the size of the plot marks. For circular plot marks, \meta{dimension}
    is the radius, for other plot marks \meta{dimension} should be about half
    the width and height.

    This option is not really necessary, since you achieve the same effect by
    specifying |scale=|\meta{factor} as a local option, where \meta{factor} is
    the quotient of the desired size and the default size. However, using
    |mark size| is a bit faster and more natural.
\end{key}

\begin{stylekey}{/tikz/every mark}
    This style is installed before drawing plot marks. For example, you can
    scale (or otherwise transform) the plot mark or set its color.
\end{stylekey}

\begin{key}{/tikz/mark options=\meta{options}}
    Redefines |every mark| such that it sets \marg{options}.
    %
\begin{codeexample}[]
\tikz \fill[fill=blue!20]
  plot[mark=triangle*,mark options={color=blue,rotate=180}]
    file{plots/pgfmanual-sine.table} |- (0,0);
\end{codeexample}
    %
\end{key}

\begin{stylekey}{/tikz/no marks}
    Disables markers (the same as |mark=none|).
\end{stylekey}
%
\begin{stylekey}{/tikz/no markers}
    Disables markers (the same as |mark=none|).
\end{stylekey}


\subsection{Smooth Plots, Sharp Plots, Jump Plots, Comb Plots and Bar Plots}

There are different things the |plot| operation can do with the points it reads
from a file or from the inlined list of points. By default, it will connect
these points by straight lines. However, you can also use options to change the
behavior of |plot|.

\begin{key}{/tikz/sharp plot}
    This is the default and causes the points to be connected by straight
    lines. This option is included only so that you can ``switch back'' if you
    ``globally'' install, say, |smooth|.
\end{key}

\begin{key}{/tikz/smooth}
    This option causes the points on the path to be connected using a smooth
    curve:
    %
\begin{codeexample}[]
\tikz\draw plot[smooth] file{plots/pgfmanual-sine.table};
\end{codeexample}

    Note that the smoothing algorithm is not very intelligent. You will get the
    best results if the bending angles are small, that is, less than about
    $30^\circ$ and, even more importantly, if the distances between points are
    about the same all over the plotting path.
\end{key}

\begin{key}{/tikz/tension=\meta{value}}
    This option influences how ``tight'' the smoothing is. A lower value will
    result in sharper corners, a higher value in more ``round'' curves. A value
    of $1$ results in a circle if four points at quarter-positions on a circle
    are given. The default is $0.55$. The ``correct'' value depends on the
    details of plot.
    %
\begin{codeexample}[]
\begin{tikzpicture}[smooth cycle]
  \draw                 plot[tension=0.2]
    coordinates{(0,0) (1,1) (2,0) (1,-1)};
  \draw[yshift=-2.25cm] plot[tension=0.5]
    coordinates{(0,0) (1,1) (2,0) (1,-1)};
  \draw[yshift=-4.5cm]  plot[tension=1]
    coordinates{(0,0) (1,1) (2,0) (1,-1)};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/smooth cycle}
    This option causes the points on the path to be connected using a closed
    smooth curve.
    %
\begin{codeexample}[]
\tikz[scale=0.5]
  \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)}
        plot               coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle;
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/const plot}
    This option causes the points on the path to be connected using piecewise
    constant series of lines:
    %
\begin{codeexample}[]
\tikz\draw plot[const plot] file{plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/const plot mark left}
    Just an alias for |/tikz/const plot|.
    %
\begin{codeexample}[]
\tikz\draw plot[const plot mark left,mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/const plot mark right}
    A variant of |/tikz/const plot| which places its mark on the right ends:
    %
\begin{codeexample}[]
\tikz\draw plot[const plot mark right,mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/const plot mark mid}
    A variant of |/tikz/const plot| which places its mark in the middle of the
    horizontal lines:
    %
\begin{codeexample}[]
\tikz\draw plot[const plot mark mid,mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}
    %
    More precisely, it generates vertical lines in the middle between each pair
    of consecutive points. If the mesh width is constant, this leads to
    symmetrically placed marks (``middle'').
\end{key}

\begin{key}{/tikz/jump mark left}
    This option causes the points on the path to be drawn using piecewise
    constant, non-connected series of lines. If there are any marks, they will
    be placed on left open ends:
    %
\begin{codeexample}[]
\tikz\draw plot[jump mark left, mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/jump mark right}
    This option causes the points on the path to be drawn using piecewise
    constant, non-connected series of lines. If there are any marks, they will
    be placed on right open ends:
    %
\begin{codeexample}[]
\tikz\draw plot[jump mark right, mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/jump mark mid}
    This option causes the points on the path to be drawn using piecewise
    constant, non-connected series of lines. If there are any marks, they will
    be placed in the middle of the horizontal line segments:
    %
\begin{codeexample}[]
\tikz\draw plot[jump mark mid, mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}

    In case of non-constant mesh widths, the same remarks as for
    |const plot mark mid| apply.
\end{key}

\begin{key}{/tikz/ycomb}
    This option causes the |plot| operation to interpret the plotting points
    differently. Instead of connecting them, for each point of the plot a
    straight line is added to the path from the $x$-axis to the point,
    resulting in a sort of ``comb'' or ``bar diagram''.
    %
\begin{codeexample}[]
\tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table};
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}[ycomb]
  \draw[color=red,line width=6pt]
    plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
  \draw[color=red!50,line width=4pt,xshift=3pt]
    plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/xcomb}
    This option works like |ycomb| except that the bars are horizontal.
    %
\begin{codeexample}[]
\tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/polar comb}
    This option causes a line from the origin to the point to be added to the
    path for each plot point.
    %
\begin{codeexample}[]
\tikz \draw plot[polar comb,
     mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt]
   coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/ybar}
    This option produces fillable bar plots. It is thus very similar to
    |ycomb|, but it employs rectangular shapes instead of line-to operations.
    It thus allows to use any fill or pattern style.
    %
\begin{codeexample}[]
\tikz\draw[draw=blue,fill=blue!60!black] plot[ybar] file{plots/pgfmanual-sine.table};
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}[ybar]
  \draw[color=red,fill=red!80,bar width=6pt]
    plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
  \draw[color=red!50,fill=red!20,bar width=4pt,bar shift=3pt]
    plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
\end{tikzpicture}
\end{codeexample}
    %
    The use of |bar width| and |bar shift| is explained in the |plothandlers|
    library documentation, section~\ref{section-plotlib-bar-handlers}. Please
    refer to page~\pageref{key-bar-width}.
\end{key}

\begin{key}{/tikz/xbar}
    This option works like |ybar| except that the bars are horizontal.
    %
\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
\tikz \draw[pattern=north west lines] plot[xbar]
   coordinates{(1,0) (0.4,1) (1.7,2) (1.6,3)};
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/ybar interval}
    As |/tikz/ybar|, this options produces vertical bars. However, bars are
    centered at coordinate \emph{intervals} instead of interval edges, and the
    bar's width is also determined relatively to the interval's length:
    %
\begin{codeexample}[]
\begin{tikzpicture}[ybar interval,x=10pt]
  \draw[color=red,fill=red!80]
    plot coordinates{(0,2) (2,1.2) (3,.3) (5,1.7) (8,.9) (9,.9)};
\end{tikzpicture}
\end{codeexample}
    %
    Since there are $N$ intervals $[x_i,x_{i+1}]$ for given $N+1$ coordinates,
    you will always have one coordinate more than bars. The last $y$ value will
    be ignored.

    You can configure relative shifts and relative bar widths, which is
    explained in the |plothandlers| library documentation,
    section~\ref{section-plotlib-bar-handlers}. Please refer to
    page~\pageref{key-bar-interval-width}.
\end{key}

\begin{key}{/tikz/xbar interval}
    Works like |ybar interval|, but for horizontal bar plots.
    %
\begin{codeexample}[]
\begin{tikzpicture}[xbar interval,x=0.5cm,y=0.5cm]
  \draw[color=red,fill=red!80]
    plot coordinates {(3,0) (2,1) (4,1.5) (1,4) (2,6) (2,7)};
\end{tikzpicture}
\end{codeexample}
    %
\end{key}

\begin{key}{/tikz/only marks}
    This option causes only marks to be shown; no path segments are added to
    the actual path. This can be useful for quickly adding some marks to a
    path.
    %
\begin{codeexample}[]
\tikz \draw (0,0) sin (1,1) cos (2,0)
  plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)};
\end{codeexample}
\end{key}