summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex111
1 files changed, 102 insertions, 9 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
index f31ef4b925f..63ce93068d6 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex
@@ -3,37 +3,80 @@
\subsection{Miscellaneous Options}
\label{pgfplots:misc}
-\begin{pgfplotskey}{disablelogfilter=\mchoice{true,false} (initally false, default true)}
+\begin{pgfplotskey}{disablelogfilter=\mchoice{true,false} (initially false, default true)}
Disables numerical evaluation of $\log(x)$ in \TeX. If you specify this option, any plot coordinates and tick positions must be provided as $\log(x)$ instead of $x$. This may be faster and -- possibly -- more accurate than the numerical log. The current implementation of $\log(x)$ normalizes~$x$ to $m\cdot 10^e$ and computes
\[ \log(x) = \log(m) + e \log(10) \]
-where $y = \log(m)$ is computed with a newton method applied to $\exp(y) - m$. The normalization involves string parsing without \TeX-registers. You can savely evaluate $\log(1\cdot 10^{-7})$ although \TeX-registers would produce an underflow for such small numbers.
+where $y = \log(m)$ is computed with a Newton method applied to $\exp(y) - m$. The normalization involves string parsing without \TeX-registers. You can safely evaluate $\log(1\cdot 10^{-7})$ although \TeX-registers would produce an underflow for such small numbers.
\end{pgfplotskey}
\label{sec:disabledatascaling}%
-\begin{pgfplotskey}{disabledatascaling=\mchoice{true,false} (initally false, default true)}
+\begin{pgfplotskey}{disabledatascaling=\mchoice{true,false} (initially false, default true)}
\index{Accuracy!Data Transformation}%
\index{Errors!dimension too large}%
Disables internal re-scaling of input data. Normally, every input data like plot coordinates, tick positions or whatever, are parsed without using \TeX's limited number precision. Then, a transformation like
\[ T(x) = 10^{q-m} \cdot x - a \]
is applied to every input coordinate/position where $m$ is ``the order of $x$'' base~$10$. Example: $x=1234 = 1.234\cdot 10^3$ has order~$m=4$ while $x=0.001234 = 1.234\cdot 10^{-3}$ has order $m=-2$. The parameter~$q$ is the order of the axis' width/height.
-The \textbf{effect} of the transformation is that your plot coordinates can be of \emph{arbitrary magnitude} like $0.0000001$ and $0.0000004$. For these two coordinates, \PGFPlots\ will use 100pt and 400pt internally. The transformation is quit fast since it relies only on period shifts. This scaling allows precision beyond \TeX's capabilities.
+The \textbf{effect} of the transformation is that your plot coordinates can be of \emph{arbitrary magnitude} like $0.0000001$ and $0.0000004$. For these two coordinates, \PGFPlots\ will use 100pt and 400pt internally. The transformation is quite fast since it relies only on period shifts. This scaling allows precision beyond \TeX's capabilities.
%\footnote{Please note that while plot coordinates can be of quite large magnitude like $10^12$ or $10^{-9}$, \PGFPlots\ still uses \TeX-registers internally (the math parser of \PGF). If your axis interval is $[1234567.8, 1234567.9]$ or something like that, }.
-The option ``|disabledatascaling|'' disables this data transformation. This has two consequences: first, coordinate expressions like \parg{{\normalfont\texttt{axis cs:}}x,y} have the same effect like \parg{x,y}, no re-scaling is applied. Second, coordinates are restricted to what \TeX\ can handle\footnote{Please note that the axis' scaling requires to compute $1/( x_\text{max} - x_{\text{min}} )$. The option \protect\pgfmanualpdfref{disabledatascaling}{\texttt{disabledatascaling}} may lead to overflow or underflow in this context, so use it with care! Normally, the data scale transformation avoids this problem.}.
+The option ``|disabledatascaling|'' disables this data transformation. This has two consequences: first, coordinate expressions like \parg{{\normalfont\texttt{axis cs:}}x,y} have the same effect as \parg{x,y}, no re-scaling is applied. Second, coordinates are restricted to what \TeX\ can handle\footnote{Please note that the axis' scaling requires to compute $1/( x_\text{max} - x_{\text{min}} )$. The option \protect\pgfmanualpdfref{disabledatascaling}{\texttt{disabledatascaling}} may lead to overflow or underflow in this context, so use it with care! Normally, the data scale transformation avoids this problem.}.
So far, the data scale transformation applies only to normal axis (logarithmic scales do not need it).
\end{pgfplotskey}
\begin{pgfplotskey}{execute at begin plot=\marg{commands}}
-This axis option allows to invoke \marg{commands} at the beginning of each |\addplot| command. The argument \marg{commands} can be any \TeX\ content.
+This axis option allows to invoke \meta{commands} at the beginning of each |\addplot| command. The argument \meta{commands} can be any \TeX\ content.
You may use this in conjunction with |x filter=...| to reset any counters or whatever. An example would be to change every $4$th coordinate.
\end{pgfplotskey}
\begin{pgfplotskey}{execute at end plot=\marg{commands}}
-This axis option allows to invoke \marg{commands} after each |\addplot| command. The argument \marg{commands} can be any \TeX\ content.
+This axis option allows to invoke \meta{commands} after each |\addplot| command. The argument \meta{commands} can be any \TeX\ content.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{execute at begin plot visualization=\marg{commands}}
+Allows to add customized code which is executed at the beginning of each plot visualization. In contrast to |execute at begin plot|, this happens not immediately during |\addplot|, but late during the postprocessing of |\end{axis}| when actual drawing commands are generated.
+
+One possible application is shown below: suppose you want to use |\usepackage{ocg}| in order to switch layers dynamically, for example in a beamer package. This can be implemented as follows:
+% \usepackage[pdftex]{ocg}
+\begin{codeexample}[]
+% requires \usepackage[pdftex]{ocg}
+\begin{tikzpicture}
+\begin{axis}[
+ title=Dynamic PDF Layer Support (see Acrobat Layers),
+ view={110}{35}]
+\addplot3+[
+ execute at begin plot visualization=\begin{ocg}{First Layer}{FirstLayer}{0},
+ execute at end plot visualization=\end{ocg},
+]
+ coordinates {(0,0,12) (0,1,2) (1,0,6) (0,0,12)};
+
+\addplot3+[
+ execute at begin plot visualization=\begin{ocg}{Second Layer}{SecondLayer}{0},
+ execute at end plot visualization=\end{ocg},
+]
+ coordinates {(0,0,9) (0,1,8) (1,0,4) (0,0,9)};
+
+\addplot3+[
+ execute at begin plot visualization=\begin{ocg}{Third Layer}{ThirdLayer}{0},
+ execute at end plot visualization=\end{ocg},
+]
+ coordinates {(0,0,1) (0,1,7) (1,0,3) (0,0,1)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ \noindent The |execute *| hooks insert the \textsc{ocg}-statements at the correct positions, and the single plot commands are added to different dynamic layers. Use the Acrobat Reader and its ``Layers'' Tab to switch each of them on or off. Note that it would not be enough to add the |\begin{ocg}...| statements right into the text since \PGFPlots\ postpones drawing commands until |\end{axis}| (splitting of survey and visualization phase).
+
+ See \url{http://www.texample.net/weblog/2008/nov/02/creating-pdf-layers} for more details on \textsc{ocg} and how to obtain it.
+
+
+ Technical note: these hooks are also inserted for |\pgfplotsextra| commands.
+\end{pgfplotskey}
+
+\begin{pgfplotskey}{execute at end plot visualization=\marg{commands}}
+This is the counter--part of |execute at begin plot visualization|.
\end{pgfplotskey}
\begin{pgfplotskey}{forget plot=\marg{true,false} (initially false)}
@@ -96,7 +139,7 @@ This axis option allows to invoke \marg{commands} after each |\addplot| command.
\end{pgfplotskey}
\begin{pgfplotscodekey}{before end axis}
-Allows to insert \marg{commands} just before the axis is ended. This option takes effect inside of the clipped area.
+Allows to insert \meta{commands} just before the axis is ended. This option takes effect inside of the clipped area.
\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
before end axis/.code={
@@ -114,7 +157,7 @@ Allows to insert \marg{commands} just before the axis is ended. This option take
\end{pgfplotscodekey}
\begin{pgfplotscodekey}{after end axis}
-Allows to insert \marg{commands} right after the end of the clipped drawing commands. While |befor end axis| has the same effect as if \marg{commands} had been placed inside of your axis, |after end axis| allows to access axis coordinates without being clipped.
+Allows to insert \meta{commands} right after the end of the clipped drawing commands. While |before end axis| has the same effect as if \meta{commands} had been placed inside of your axis, |after end axis| allows to access axis coordinates without being clipped.
\begin{codeexample}[]
\pgfplotsset{every axis/.append style={
after end axis/.code={
@@ -164,6 +207,56 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm
Please note that this feature does not affect plot marks. I think it looks unfamiliar if plot marks are crossed by axis descriptions.
\end{pgfplotskey}
+
+\begin{pgfplotskeylist}{%
+ visualization depends on=\meta{\textbackslash macro} (initially empty),%
+ visualization depends on=\meta{expression}\texttt{\textbackslash as}\meta{\textbackslash macro} (initially empty),
+ visualization depends on=\texttt{value }\meta{content}\texttt{\textbackslash as}\meta{\textbackslash macro} (initially empty)}
+ Allows to communicate data to \PGFPlots\ which is essential to perform the visualization although \PGFPlots\ isn't aware of it.
+
+ Suppose you want a scatter plot, which depends on the $(x,y)$ coordinates, the |point meta| data to draw individual colors and furthermore data which influences the |mark size|. Thus, you need a total of~$4$ coordinates for every data point, although \PGFPlots\ supports only $3$ in its initial configuration.
+
+ Before we actually come to the main point of the problem, we'll talk about how to get a scatter plot which has individual colors \emph{and} individual sizes. It is not sufficient to set |mark size| alone, since |mark size| is evaluated only once, before markers are processed (the same holds for |every mark|). Thus, we can use |scatter| combined with
+
+ |scatter/@pre marker code/.append style={/tikz/mark size=\perpointmarksize}|.
+
+ \noindent The |@pre marker code| is installed for every marker of a scatter plot individually. Now, we come to the problem as such: where can we get the value for |mark size|, in our case called |\perpointmarksize|?
+
+ A solution is |visualization depends on| (using the second input syntax at this point):
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}
+ \addplot+[
+ scatter,
+ scatter src=y,
+ samples=40,
+ visualization depends on=
+ {5*cos(deg(x)) \as \perpointmarksize},
+ scatter/@pre marker code/.append style=
+ {/tikz/mark size=\perpointmarksize}
+ ]
+ {sin(deg(x))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ Here, we define |\perpointmarksize| as |5*cos(deg(x))|. The expression will be evaluated together with all other coordinates. Thus, everything which is available during the survey phase can be used here. This includes the final coordinates |x|, |y|, |z|; the constant |meta| expands to the current per point meta data. Furthermore, |\thisrow|\marg{colname} expands to the value of a table column.
+
+ The command |visualization depends on| evaluates and remembers every value in internal data structures. The remembered value is then available as \meta{\textbackslash macro} during the visualization phase. In our example, the |@pre marker code| is evaluated during the visualization phase and applies |mark size=5*cos(deg(x))|.
+
+ The first syntax, |visualization depends on=|\meta{\textbackslash macro}, tells \PGFPlots\ to use an already defined \meta{\textbackslash macro}. The second syntax with \meta{content}|\as|\meta{\textbackslash macro} provides also the value.
+
+ There can be more than one |visualization depends on| phrase.
+
+ In case the stored value is not of numerical type\footnote{Or if it is just a constant and you'd like to improve speed.}, you can use the prefix `|value|' before the argument, i.e.
+
+ |visualization depends on=value |\meta{\textbackslash macro} or
+
+ |visualization depends on=value |\meta{content}|\as |\meta{\textbackslash macro}.
+
+ Such a value will be expanded and stored, but not parsed as number (at least not by \PGFPlots).
+\end{pgfplotskeylist}
+
\begin{key}{/pgf/fpu=\marg{true,false} (initially true)}
\index{Precision}
This key activates or deactivates the floating point unit. If it is disabled (|false|), the core \PGF\ math engine written by Mark Wibrow and Till Tantau will be used for |plot expression|.