diff options
author | Karl Berry <karl@freefriends.org> | 2011-08-01 00:47:16 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2011-08-01 00:47:16 +0000 |
commit | aec2bbc3994991ebc6c5f4dbc90ad15c55f1a1fb (patch) | |
tree | 8940f33f6b173fb5cc630cc58ed4b791ad29e3fe /Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.miscellaneous.tex | |
parent | 868233e6288b5e35a7d7aabd79bf8e56a802bc12 (diff) |
pgfplots 1.5 (29jul11)
git-svn-id: svn://tug.org/texlive/trunk@23292 c570f23f-e606-0410-a88d-b1316a301751
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.tex | 111 |
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|. |