diff options
author | Karl Berry <karl@freefriends.org> | 2014-02-27 00:01:50 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-02-27 00:01:50 +0000 |
commit | 90ae413a94da014dbf7a6a8ab584f7c668483a5a (patch) | |
tree | 4e0528a2b2fb2004988e7fc804ea2f1354f1f5d5 /Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex | |
parent | 800cc56380d1edfe567a6a66bef13e8950eb2b0c (diff) |
pgf 3.0.0
git-svn-id: svn://tug.org/texlive/trunk@33057 c570f23f-e606-0410-a88d-b1316a301751
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 | 202 |
1 files changed, 138 insertions, 64 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 00f8d874b6c..35f83f1546f 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,17 +7,22 @@ % % See the file doc/generic/pgf/licenses/LICENSE for more details. - \section{Plots of Functions} \label{section-tikz-plots} -\subsection{When Should One Use \tikzname\ for Generating 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} -There exist many powerful programs that produce plots, examples are -\textsc{gnuplot} or \textsc{mathematica}. These programs can produce +\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 @@ -27,41 +32,41 @@ 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. -\emph{Note that is often not necessary to use \tikzname\ for plots.} -Programs like \textsc{gnuplot} can produce very sophisticated plots -and it is usually much easier to simply include these plots as a -finished \textsc{pdf} or PostScript graphics. - -However, there are a number of reasons why you may wish to invest time -and energy into mastering the \pgfname\ commands for creating plots: - -\begin{itemize} -\item - Virtually all plots produced by ``external programs'' use different - fonts from the one used in your document. -\item - Even worse, formulas will look totally different, if they can be - rendered at all. -\item - Line width will usually be too large or too small. -\item - Scaling effects upon inclusion can create a mismatch between sizes - in the plot and sizes in the text. -\item - The automatic grid generated by most programs is mostly - distracting. -\item - The automatic ticks generated by most programs are cryptic - numerics. (Try adding a tick reading ``$\pi$'' at the right point.) -\item - Most programs make it very easy to create ``chart junk'' in a most - convenient fashion. All show, no content. -\item - Arrows and plot marks will almost never match the arrows used in the - rest of the document. -\end{itemize} +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: -The above list is not exhaustive, unfortunately. +\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 that the + |plot| path operation and produces complete plots including axes and + ticks. The downside is that you cannot use it to ``just'' to 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} @@ -87,7 +92,7 @@ The syntax of the |plot| comes in different versions. coordinate of the curve. \end{pathoperation} -The \meta{further arguments} are used in three different ways to +The \meta{further arguments} are used in different ways to specifying the coordinates of the points to be plotted: \begin{enumerate} @@ -107,7 +112,7 @@ These different ways are explained in the following. \subsection{Plotting Points Given Inline} -In the first two cases, the points are given directly in the \TeX-file +Points can be given directly in the \TeX-file as in the following example: \begin{codeexample}[] @@ -131,12 +136,19 @@ 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. Anything following the two numbers on the line is -ignored. Also, lines starting with a |%| or a |#| are ignored as well -as empty lines. (This is exactly the format that \textsc{gnuplot} -produces when you say |set terminal table|.) If necessary, more -formats will be supported in the future, but it is usually easy to -produce a file containing data in this form. +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}; @@ -202,7 +214,7 @@ is evaluated: \end{key} \begin{key}{/tikz/domain=\meta{start}|:|\meta{end} (initially -5:5)} - Sets the domain between which the samples are taken. + Sets the domain from which the samples are taken. \end{key} \begin{key}{/tikz/samples at=\meta{sample list}} @@ -213,7 +225,7 @@ is evaluated: syntax, so you can use |...| inside the \meta{sample list}. When this option is used, the |samples| and |domain| option are - overruled. The other ways round, setting either |samples| or + overruled. The other way round, setting either |samples| or |domain| will overrule this option. \end{key} @@ -225,6 +237,7 @@ is evaluated: \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} @@ -246,7 +259,7 @@ is evaluated: 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 on such a function +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 @@ -256,17 +269,14 @@ 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 you main |.tex| file. If no \meta{id} is +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}|. However, -there is just one difference: |gnuplot| supports a ``type'' field following -the coordinates. If this type field contains `|u|' which means unbounded, \tikzname\ will -ignore the complete coordinate\footnote{Thanks to Andy Schlaikjer for this patch.}. +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} @@ -342,7 +352,7 @@ plots, use |t| as the variable for parametric plots. Here are some examples: \end{codeexample} -The plot in influenced by the following options: First, the options +The plot is influenced by the following options: First, the options |samples| and |domain| explained earlier. Second, there are some more specialized options. @@ -357,6 +367,28 @@ specialized options. \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, @@ -419,7 +451,7 @@ In detail, the following options govern how marks are drawn: marks. One plot mark is special: the |ball| plot mark is available only - it \tikzname. The |ball color| determines the balls's color. Do not use + 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. @@ -552,7 +584,8 @@ use options to change the behavior of |plot|. \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}; @@ -573,9 +606,22 @@ use options to change the behavior of |plot|. \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: + 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}; @@ -583,11 +629,26 @@ use options to change the behavior of |plot|. \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: \begin{codeexample}[] \tikz\draw plot[jump mark right, 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} @@ -632,7 +693,9 @@ use options to change the behavior of |plot|. \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}; @@ -646,7 +709,10 @@ 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} @@ -659,7 +725,10 @@ use options to change the behavior of |plot|. \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] @@ -667,9 +736,14 @@ use options to change the behavior of |plot|. 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 width, 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} |