| 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} |