summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2010-04-03 23:06:54 +0000
committerKarl Berry <karl@freefriends.org>2010-04-03 23:06:54 +0000
commit36080b5cf06fe9bdde3b1edb30fd795a58e6bf10 (patch)
tree172e727ca5a42cbd0c2440855dbb81f3a5c2148e /Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
parente27b3d0aaf815fdab1497a0a827998ac044e245d (diff)
pgfplots update (1apr10)
git-svn-id: svn://tug.org/texlive/trunk@17670 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex72
1 files changed, 60 insertions, 12 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
index ae02b4c8bb8..4af602d4fd8 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.axis-addplot.tex
@@ -133,7 +133,7 @@ coordinates
\end{tikzpicture}
\end{codeexample}
-Inside of an axis environment, the |\addplot| command is the main user interface. It comes in two variants: |\addplot| for twodimensional visualization and \verbpdfref{\addplot3} for threedimensional visualization.
+Inside of an axis environment, the |\addplot| command is the main user interface. It comes in two variants: |\addplot| for two--dimensional visualization and \verbpdfref{\addplot3} for three--dimensional visualization.
\begin{command}{\addplot\oarg{options} \meta{input data} \meta{trailing path commands};}
\label{cmd:pgfplots:addplot}
@@ -141,7 +141,7 @@ This is the main plotting command, available within each axis environment. It ca
It reads point coordinates from one of the available input sources specified by \meta{input data}, updates limits, remembers \meta{options} for use in a legend (if any) and applies any necessary coordinate transformations (or logarithms).
-The \meta{options} can be omitted in which case the next entry from the |cycle list| will be inserted as \meta{options}. These keys characterize the plot's type like linear interpolation, smooth plot, constant interpolation, bar plot, mesh plots, surface plots or whatever and define colors, markers and line specifications\footnote{In version 1.2.2 and earlier, there was an explicit distiction between ``behaviour'' options like error bars, domain, number of samples etc.\ and ``style options'' like color, line width, markers etc. This distiction is obsolete now, simply collect everything into \meta{options}.}\index{Behavior Options}\index{Options!Distinction Behavior, Style Options}. Plot variants like error bars, the number of samples or a sample domain can also be configured in \meta{options}.
+The \meta{options} can be omitted in which case the next entry from the |cycle list| will be inserted as \meta{options}. These keys characterize the plot's type like linear interpolation, smooth plot, constant interpolation, bar plot, mesh plots, surface plots or whatever and define colors, markers and line specifications\footnote{In version 1.2.2 and earlier, there was an explicit distinction between ``behaviour'' options like error bars, domain, number of samples etc.\ and ``style options'' like color, line width, markers etc. This distinction is obsolete now, simply collect everything into \meta{options}.}\index{Behavior Options}\index{Options!Distinction Behavior, Style Options}. Plot variants like error bars, the number of samples or a sample domain can also be configured in \meta{options}.
The \meta{input data} is one of several coordinate input tools which are described in more detail below. Finally, if |\addplot| successfully processed all coordinates from \meta{input data}, it generates \Tikz\ paths to realize the drawing operations. Any \meta{trailing path commands} are appended to the final drawing command, allowing to continue the \Tikz\ path (from the last plot coordinate).
@@ -177,7 +177,7 @@ Some more details:
\end{codeexample}
You can represent arbitrarily small or very large numbers as long as its logarithm can be represented as a \TeX-length (up to about~$16384$). Of course, any coordinate~$x\le 0$ is not possible since the logarithm of a non-positive number is not defined. Such coordinates will be skipped automatically (using the initial configuration |unbounded coords=discard|).
- \item For normal (non--logarithmic) axes, \PGFPlots\ applies floating point arithmetics to support large or small numbers like 0.00000001234 or $1.234\cdot 10^{24}$. Its number range is much larger than \TeX's native support for numbers. The relative precision is between $4$ and $7$ significant decimal digits for the mantisse.
+ \item For normal (non--logarithmic) axes, \PGFPlots\ applies floating point arithmetics to support large or small numbers like 0.00000001234 or $1.234\cdot 10^{24}$. Its number range is much larger than \TeX's native support for numbers. The relative precision is between $4$ and $7$ significant decimal digits for the mantissa.
As soon as the axes limits are completely known, \PGFPlots\ applies a transformation which maps these floating point numbers into \TeX-precision using transformations
\[ T_x(x) = 10^{s_x} \cdot x - a_x
@@ -373,11 +373,11 @@ or
\end{codeexample}
Alternatively, you can load the table \emph{once} and use it \emph{multiple} times:
\begin{codeexample}[code only]
-\pgfplotstableread{datafile.dat}\table
+\pgfplotstableread{datafile.dat}\loadedtable
...
-\addplot table[x=dof,y=L2] from \table;
+\addplot table[x=dof,y=L2] from \loadedtable;
...
-\addplot table[x=dof,y=Lmax] from \table;
+\addplot table[x=dof,y=Lmax] from \loadedtable;
...
\end{codeexample}
I am not really sure how much time can be saved, but it works anyway. As a rule of thumb, decide as follows:
@@ -432,6 +432,9 @@ Summary and remarks:
\end{itemize}
\end{addplotoperation}
+\subsubsection*{Keys To Configure Table Input}
+The following list of keys allow different methods to select input data or different input formats. Note that the common prefix `|table/|' can be omitted if these keys are set after |\addplot table|\oarg{options}. The |/pgfplots/| prefix can always be omitted when used in a \PGFPlots\ method.
+
\begin{pgfplotskey}{table/header=\mchoice{true,false} (initially true)}
Allows to disable header identification for |plot table|. See above.
\end{pgfplotskey}
@@ -526,7 +529,7 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
%\index{y@\texttt{\textbackslash y} In Coordinate Expressions}%
\item The complete set of math expressions can be found in the \PGF\ manual. The most important mathematical operations are
- |+|, |-|, |*|, |/|, |abs|, |round|, |floor|, |mod|, |<|, |>|, |max|, |min|, |sin|, |cos|, |tan|, |deg| (conversion from radians to degrees), |rad| (conversion from degrees to radians), |atan|, |asin|, |acos|, |cot|, |sec|, |cosec|, |exp|, |ln|, |sqrt|, the constanst |pi| and |e|, |^| (power operation), |factorial|\footnote{Starting with \PGF\ versions newer than $2.00$, you can use the postfix operator \texttt{!} instead of \texttt{factorial}.}, |rand| (random between $-1$ and $1$), |rnd| (random between $0$ and $1$), number format conversions |hex|, |Hex|, |oct|, |bin| and some more. The math parser has been written by Mark Wibrow and Till Tantau~\cite{tikz}, the FPU routines have been developed as part of \PGFPlots. The documentation for both parts can be found in~\cite{tikz}.
+ |+|, |-|, |*|, |/|, |abs|, |round|, |floor|, |mod|, |<|, |>|, |max|, |min|, |sin|, |cos|, |tan|, |deg| (conversion from radians to degrees), |rad| (conversion from degrees to radians), |atan|, |asin|, |acos|, |cot|, |sec|, |cosec|, |exp|, |ln|, |sqrt|, the constants |pi| and |e|, |^| (power operation), |factorial|\footnote{Starting with \PGF\ versions newer than $2.00$, you can use the postfix operator \texttt{!} instead of \texttt{factorial}.}, |rand| (random between $-1$ and $1$), |rnd| (random between $0$ and $1$), number format conversions |hex|, |Hex|, |oct|, |bin| and some more. The math parser has been written by Mark Wibrow and Till Tantau~\cite{tikz}, the FPU routines have been developed as part of \PGFPlots. The documentation for both parts can be found in~\cite{tikz}.
Please note, however, that trigonometric functions are defined in degrees. The character `|^|' is used for exponentiation (not `|**|' as in gnuplot).
@@ -627,6 +630,16 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
\paragraph{Attention:} |samples at| overrides |domain|, even if |domain| has been set \emph{after} |samples at|! Use |samples at={}| to clear \marg{coordinate list} and re-activate |domain|.
\end{pgfplotskey}
+\begin{pgfplotskeylist}{%
+ variable=\marg{variable name} (initially x),%
+ variable y=\marg{variable name} (initially y)}
+ Defines the variables names which will be sampled in |domain| (with |variable|) and in |domain y| (with |variable y|).
+
+ The same variables are used for parametric and for non-parametric plots. Use |variable=t| to change them if you like (for |gnuplot|, there is such a distinction; see |parametric/var 1d|).
+
+ Technical remark: \Tikz\ also uses the |variable| key. However, it expects a \emph{macro} name, i.e.\ |\x| instead of just |x|. Both possibilities are accepted here.
+\end{pgfplotskeylist}
+
\subsubsection{Mathematical Expressions And File Data}
\PGFPlots\ allows to combine `|plot table|' and `|plot expression|' to get both, file input and modifications by means of mathematical expressions.
@@ -635,6 +648,8 @@ Please note that \PGF's math parser uses degrees for trigonometric functions:
Besides the already discussed possibility to provide a column selection by means of column names (|x||=|\meta{name} or |x index||=|\meta{index}, see section~\ref{pgfplots:addplot:table}), it is also possible to provide mathematical expressions as arguments.
Mathematical expressions are specified with |x expr||=|\meta{expression} inside of \meta{column selection and expressions}. They can depend on zero, one or more columns of the input file. A column is referenced using the special command `|\thisrow|\marg{column name}' within \meta{expression} (or |\thisrowno|\meta{column index}).
+
+\pgfplotstableset{begin table={\begin{tabular}[b]}}
\begin{codeexample}[vbox]
\pgfplotstabletypeset[columns={maxlevel,L2}]{plotdata/newexperiment1.dat}
@@ -721,15 +736,20 @@ Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs t
The \meta{options} determine the appearance of the plotted function; these parameters also affect the legend. There is also a set of options which are specific to the gnuplot interface. These options are described in all detail in \cite[section~18.6]{tikz}. A short summary is shown below.
+
+Some remarks:
+\begin{itemize}
+ \item The independent variable for one dimensional plots can be change with the |variable| option, just as for |plot expression|. Similarly, the second variable for two dimensional plots can be changed with |variable y|.
+
+ For |parametric| plots, the variable names need to be adjusted with |parametric/var 1d| and |parametric/var 2d| (since gnuplot uses |t| and |u,v| as initial values for |parametric| plots).
+ \item
Please note that |plot gnuplot| does not allow per point meta data (color data for each coordinate).
-Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction.
+ \item The generated output file name can be customized with |id|, see below.
+\end{itemize}
-\begin{pgfplotskey}{translate gnuplot=\mchoice{true,false} (initially true)}
- Enables or disables automatic translation of the exponentiation operator `|^|' to `|**|'.
+Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction.
- This features allows to use |^| in |plot gnuplot| instead of gnuplot's |**|.
-\end{pgfplotskey}
\end{addplotoperation}
\begin{addplotoperation}[]{function}{\marg{gnuplot code}}
@@ -742,6 +762,30 @@ Please refer to \cite[section~18.6]{tikz} for more details about |plot function|
|\addplot gnuplot |\marg{gnuplot code}|;|
\end{addplotoperation}
+\begin{pgfplotskey}{translate gnuplot=\mchoice{true,false} (initially true)}
+ Enables or disables automatic translation of the exponentiation operator `|^|' to `|**|'.
+
+ This features allows to use |^| in |plot gnuplot| instead of gnuplot's |**|.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{parametric=\mchoice{true,false} (initially false)}
+ Set this to |true| if you'd like to use parametric plots with |gnuplot|. Parametric plots use a comma separated list of expressions to make up $x(t),\, y(t)$ for a line plot or $x(u,v), \, y(u,v)\, z(u,v)$ for a mesh plot (refer to the gnuplot manual for more information about its input methods for parametric plots).
+\end{pgfplotskey}
+
+\begin{pgfplotskeylist}{%
+ parametric/var 1d=\marg{variable name} (initially t),%
+ parametric/var 2d=\marg{variable name,variable name} (initially {u,v})%
+ }
+ Allows to change the dummy variables used by |parametric| |gnuplot| plots. The initial setting is the one of |gnuplot|: to use the dummy varialbe `|t|' for parametric line plots and `|u,v|' for parametric mesh plots.
+
+ These keys are quite the same as |variable| and |variable y|, only for parametric plots. If you like to change variables for non-parametric plots, use |variable| and/or |variable y|.
+
+ In case you don't want the distinction between parametric and non-parametric plots, use
+
+ |\pgfplotsset{parametric/var 1d=,parametric/var 2d=}|.
+
+\end{pgfplotskeylist}
+
\begin{key}{/tikz/id=\marg{unique string identifier}}
A unique identifier for the current plot. It is used to generate temporary filenames for |gnuplot| output.
\end{key}
@@ -900,6 +944,10 @@ Using |gv|, I determined that the bounding box needs to be shifted |12| units to
The scaling will thus ignore the aspect ratio of the external image and prefer the one used by \PGFPlots. You will need to provide |width| and |height| to the \PGFPlots\ axis to change its scaling. Use the |scale only axis| key in such a case.
\end{addplotoperation}
+
+\subsubsection*{Keys To Configure Plot Graphics}
+The following list of keys configure |\addplot graphics|. Note that the common prefix `|plot graphics/|' can be omitted if these keys are set after |\addplot graphics|\oarg{options}. The |/pgfplots/| prefix can always be omitted when used in a \PGFPlots\ method.
+
\begin{pgfplotsxykeylist}{
plot graphics/\x min=\marg{coordinate},
plot graphics/\x max=\marg{coordinate}}