summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-plots.tex
diff options
context:
space:
mode:
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.tex202
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}