diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex | 743 |
1 files changed, 375 insertions, 368 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex index 944eeca1a12..3859a65f5c0 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex @@ -7,104 +7,99 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. -\section{Plots of Functions} +\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}.} +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} +\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. +\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. +\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. + \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. +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. + 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. + 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: - +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}|}|} + \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. @@ -112,15 +107,14 @@ 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: - +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)}; @@ -132,29 +126,28 @@ Here is an example showing the difference between |plot| and |--plot|: \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 behaviour, 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|.) - +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 behaviour, 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 @@ -166,7 +159,9 @@ The file |plots/pgfmanual-sine.table| reads: 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" @@ -174,61 +169,60 @@ 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. +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: +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. + 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. + 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. + 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}. + 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. + 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); @@ -257,87 +251,77 @@ is evaluated: \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}. +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, +|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}|. +|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. + \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: +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. + \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: - +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); @@ -351,215 +335,225 @@ plots, use |t| as the variable for parametric plots. Here are some examples: \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. +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: + 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: + 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|. + Same as |range|. \end{key} \begin{key}{/tikz/xrange=\meta{start}|:|\meta{end}} - Set the $x$-range. This makes sense only for parametric plots. + 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 |$|.%$ + 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. + 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 + 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.'' + % + 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 + 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: + % + 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. +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. + 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. + 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} + \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. - + 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. - + 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. - + 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. + 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. + 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. + 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}. + 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|). + Disables markers (the same as |mark=none|). \end{stylekey} +% \begin{stylekey}{/tikz/no markers} - Disables markers (the same as |mark=none|). + 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|. +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|. + 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: - + 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. + 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. - + 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] @@ -570,93 +564,103 @@ use options to change the behavior of |plot|. 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. - + 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: - + 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|. + 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: + 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: + 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''). + % + 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: - + 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: - + 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: - + 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 right, mark=*] file{plots/pgfmanual-sine.table}; +\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. + 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.'' - + 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} @@ -669,34 +673,35 @@ use options to change the behavior of |plot|. 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. - + 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. - + 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. - + 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} @@ -709,59 +714,61 @@ use options to change the behavior of |plot|. 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 plot - handler library documentation, - section~\ref{section-plotlib-bar-handlers}. Please refer to - page~\pageref{key-bar-width}. + % + The use of |bar width| and |bar shift| is explained in the plot handler + 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. - + This option works like |ybar| except that the bars are horizontal. + % \begin{codeexample}[] \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: - + 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. + % + 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 plot handler library documentation, - section~\ref{section-plotlib-bar-handlers}. Please refer to - page~\pageref{key-bar-interval-width}. + You can configure relative shifts and relative bar widths, which is + explained in the plot handler 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. - + 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. - + 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)}; |