diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex | 1490 |
1 files changed, 1172 insertions, 318 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex index 40049e9d851..e5ba9fe8f32 100644 --- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex @@ -77,7 +77,7 @@ coordinates \begin{axis} \addplot plot [id=parable,domain=-5:5] - function{4*x**2 - 5} + gnuplot{4*x**2 - 5} node[pin=180:{$4x^2-5$}]{}; \end{axis} \end{tikzpicture} @@ -129,6 +129,7 @@ Some more details: \item For normal plots, \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 at least~$5$ significant decimal digits for the mantisse. 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 \text{ and } T_y(y) = 10^{s_y} \cdot y - a_y \] with properly chosen integers $s_x, s_y \in \Z$ and shifts $a_x,a_y\in \R$. Section~\ref{sec:disabledatascaling} contains a description of |disabledatascaling| and provides more details about the transformation. + \index{Accuracy!Floating Point in \PGFPlots}% \item As a consequence of the coordinate parsing routines, you can't use the mathematical expression parsing method of \PGF\ as coordinates (that means: you will need to provide coordinates without suffixes like ``cm'' or ``pt'' and you can't invoke mathematical functions). @@ -136,12 +137,13 @@ Some more details: The automatic computation of axis limits works as follows: \begin{enumerate} \item Every coordinate will be checked. Care has been taken to avoid \TeX's limited numerical capabilities. - \item Since more than one |\addplot| command may be used inside an |\begin{axis}...\end{axis}|, all drawing commands will be postponed until |\end{axis}|. + \item Since more than one |\addplot| command may be used inside of |\begin{axis}...\end{axis}|, all drawing commands will be postponed until |\end{axis}|. \end{enumerate} \end{itemize} \end{command} -\subsubsection{Providing Input Coordinates} +\subsubsection{Coordinate Lists} +\label{pgfplots:providing:input} \begin{addplotoperation}[]{coordinates}{\marg{coordinate list}} The `|plot coordinates|' command is provided by \Tikz\ and reads its input data from a sequence of point coordinates. @@ -173,8 +175,19 @@ or These error coordinates are only used in case of error bars, see section~\ref{sec:errorbars}. You will also need to configure whether these values denote absolute or relative errors. The coordinates as such can be numbers as |+5|, |-1.2345e3|, |35.0e2|, |0.00000123| or |1e2345e-8|. They are not limited to \TeX's precision. + +Furthermore, |plot coordinates| allows to define ``meta data'' for each coordinate. The interpretation of meta data depends on the visualization technique: for scatter plots, meta data can be used to define colors or style associations for every point (see page~\pageref{pgfplots:scatterclasses} for an example). Meta data (if any) must be provided after the coordinates and after error bar bounds (if any) in square brackets: +\begin{codeexample}[code only] +\addplot plot coordinates { + (1300,1e-6) [1] + (2600,5e-7) [2] + (4000,1e-7) [3] +}; +\end{codeexample} +Please refer to the documentation of |scatter src| on page~\pageref{pgfplots:scatter:src} for more information about per point meta data. \end{addplotoperation} +\subsubsection{Reading Coordinates From Files} \begin{addplotoperation}[]{file}{\marg{name}} \PGFPlots\ supports two ways to read plot coordinates of external files, and one of them is the \Tikz-command `|plot file|'. It is to be used like @@ -204,13 +217,20 @@ Plot file accepts one optional argument, \noindent which allows to skip over a non-comment header line. This allows to read the same input files as |plot table| by skipping over column names. Please note that comment lines do not count as lines here. +The input method |plot file| can also read meta data for every coordinate. As already explained for |plot coordinates| (see above), meta data can be used to change colors or other style parameters for every marker separately. Now, if |scatter src| is set to |explicit| or to |explicit symbolic| and the input method is |plot file|, one further element will be read from disk - for every line. Meta data is always the last element which is read. See page~\pageref{pgfplots:scatter:src} for information and examples about per point meta data and page~\pageref{pgfplots:scatterclasses} for an application example using |scatter/classes|. + + Plot file is very similar to |plot table|: you can achieve the same effect with \begin{codeexample}[code only] \addplot table[x index=0,y index=0,header=false] {datafile.dat}; \end{codeexample} \noindent Due to its simplicity, |plot file| is slightly faster while |plot table| allows higher flexibility. + +Technical note: every opened file will be protocolled into your log file. \end{addplotoperation} +\subsubsection{Reading Coordinates From Tables} + \begin{addplotoperation}[]{table}{\oarg{column selection}\marg{file}} \PGFPlots\ comes with a new plotting command, the `|plot table|' macro. It's usage is similar in spirit to `|plot file|', but its flexibility is higher. Given a data file like \begin{codeexample}[code only] @@ -230,7 +250,7 @@ one may want to plot `|dof|' versus `|L2|' or `|dof|' versus `|Lmax|'. This can \begin{tikzpicture} \begin{loglogaxis}[ xlabel=Dof, - ylabel=$L_2$ error$] + ylabel=$L_2$ error] \addplot table[x=dof,y=L2] {datafile.dat}; \end{loglogaxis} \end{tikzpicture} @@ -240,7 +260,7 @@ or \begin{tikzpicture} \begin{loglogaxis}[ xlabel=Dof, - ylabel=$L_infty$ error$] + ylabel=$L_infty$ error] \addplot table[x=dof,y=Lmax] {datafile.dat}; \end{loglogaxis} \end{tikzpicture} @@ -268,14 +288,17 @@ If you do prefer to access columns by column indices instead of column names (or Summary and remarks: \begin{itemize} - \item Use |plot table[x=|\marg{column name}|,y=|\marg{column name}|]}| to access column names. Those names are case sensitive and need to exist. - \item Use |plot table[x index=|\marg{column index}|,y index=|\marg{column index}|]}| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$. + \item Use |plot table[x=|\marg{column name}|,y=|\marg{column name}|]| to access column names. Those names are case sensitive and need to exist. + \item Use |plot table[x index=|\marg{column index}|,y index=|\marg{column index}|]| to access column indices. Indexing starts with~$0$. You may also use an index for~$x$ and a column name for~$y$. \item Use |plot table[header=false] |\marg{file name} if your input file has no column names. Otherwise, the first non-comment line is checked for column names: if all entries are numbers, they are treated as numerical data; if one of them is not a number, all are treated as column names. \item It is possible to read error coordinates from tables as well. Simply add options `|x error|', `|y error|' or `|x error index|'/`|y error index|' to \marg{source columns}. See section~\ref{sec:errorbars} for details about error bars. + \item It is possible to read per point meta data (usable in |scatter src|, see page~\pageref{pgfplots:scatter:src}) as has been discussed for |plot coordinates| and |plot file| above. The meta data column can be provided using the |meta| key (or the |meta index| key). \item Use |plot table[|\meta{source columns}|] from |\marg{\textbackslash macro} to use a pre--read table. Tables can be read using \begin{codeexample}[code only] \pgfplotstableread{datafile.dat}\macroname. \end{codeexample} + The keyword `|from|' can be omitted. + \item The accepted input format of those tables is as follows: \begin{itemize} \item Columns are usually separated by white spaces (at least one tab or space). @@ -292,6 +315,10 @@ Summary and remarks: \item The accepted number format is the same as for `|plot coordinates|', see above. \item If you omit column selectors, the default is to plot the first column against the second. That means |plot table| does exactly the same job as |plot file| for this case. \end{itemize} + \item It \emph{is} possible to create new columns out of existing ones, see the \PGFPlotstable\ manual section ``Postprocessing Data in New Columns''. + + In this context, you should consider using the key |read completely|, see below. + \item Technical note: every opened file will be protocolled into your log file. \end{itemize} \end{addplotoperation} @@ -305,115 +332,244 @@ Summary and remarks: Please note that column \emph{aliases} will be considered if unknown column names are used. Please refer to the manual of \PGFPlotstable\ which comes with this package. \end{pgfplotsxykeylist} \begin{pgfplotsxykeylist}{% - \x\ error=\marg{column name}, - \x\ error index=\marg{column index}} + table/\x\ error=\marg{column name}, + table/\x\ error index=\marg{column index}} These keys define input sources for error bars with explicit error values. Please see section~\ref{sec:errorbars} for details. \end{pgfplotsxykeylist} +\begin{pgfplotsxykeylist}{% + table/meta=\marg{column name}, + table/meta index=\marg{column index}} + These keys define input sources for per point meta data. Please see page~\pageref{pgfplots:scatter:src} for details about meta data or the documentation for |plot coordinates| and |plot file| for further information. +\end{pgfplotsxykeylist} \begin{key}{/pgfplots/table/col sep=\mchoice{space,comma,semicolon,colon,braces} (initially space)} Allows to choose column separators for |plot table|. Please refer to the manual of \PGFPlotstable\ which comes with this package for details about |col sep|. \end{key} +\begin{key}{/pgfplots/table/read completely=\marg{true,false} (initially false)} + Allows to customize |\addplot table|\marg{file name} such that it always reads the entire table into memory. + This key has just one purpose, namely to create postprocessing columns on-the-fly and to plot those columns afterwards. This ``lazy evaluation'' which creates missing columns on-the-fly is documented in the \PGFPlotstable\ manual (in section ``Postprocessing Data in New Columns''). -\begin{addplotoperation}[]{function}{\marg{gnuplot code}} -The plot function command uses the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot function| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with |plot function| (it configures high precision output). You should use different ids to avoid conflicts in such a case.}). + \paragraph{Attention:} Usually, |\addplot table| only picks required entries, requiring linear runtime complexity. As soon as |read completely| is activated, tables are loaded completely into memory. Due to datastructures issues (``macro append runtime''), the runtime complexity for |read completely| is $O(N^2)$ where $N$ is the number of rows. Thus: use this feature only for ``small'' tables. +\end{key} -Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example -\begin{codeexample}[code only] -pdflatex -shell-escape filename.tex. +\subsubsection{Computing Coordinates with Mathematical Expressions} + +\begin{addplotoperation}[]{expression \marg{math expr}}{} + This input method allows to provide mathematical expressions which will be sampled. But unlike |plot gnuplot|, the expressions are evaluated using the math parser of \PGF, no external program is required. + + Plot expression samples |x| from the interval $[a,b]$ where $a$ and $b$ are specified with the |domain| key. The number of samples can be configured with |samples=|\meta{N} as for plot gnuplot. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot expression {x^2 + 4}; + \addplot expression {-5*x^3 - x^2}; +\end{axis} +\end{tikzpicture} \end{codeexample} -Sometimes it is called |shell-escape| or |enable-write18|. + +Please note that \PGF's math parser uses degrees for trigonometric functions: \begin{codeexample}[] \begin{tikzpicture} \begin{axis} -\addplot plot[id=sin] - function{sin(x)}; + \addplot expression[domain=0:360] + {sin(x)}; \end{axis} \end{tikzpicture} \end{codeexample} +\noindent If you want to use radians, use +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis} + \addplot expression[domain=-pi:pi] + {sin(deg(x))}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent to convert the radians to degrees. The plot expression parser also accepts some more options like |samples at=|\marg{coordinate list} or |domain=|\meta{first}|:|\meta{last} which are described below. + +\paragraph{Remarks} +\begin{enumerate} + \item What really goes on is a loop which assigns the current sample coordinate to the macro |\x|. \PGFPlots\ defines a math constant |x| which always has the same value as |\x|. + + In short: it is the same whether you write |\x| or just |x| inside of math expressions. + + The variable name can be customized using |variable=\t|, for example. Then, |x| will be the same as |\t| (there won't be a short-hand name for user defined variable names). +\index{x@\texttt{\textbackslash x} In Coordinate Expressions}% +%\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}. + + Please note, however, that trigonometric functions are defined in degrees. The character `|^|' is used for exponentiation (not `|**|' as in gnuplot). + + \item If the $x$ axis is logarithmic, samples will be drawn logarithmically. + + \item Please note that plot expression does not allow per point meta data. +\end{enumerate} + +\paragraph{About the precision and number range:} +\index{Accuracy!High Precision for Plot Expression}% +\index{Errors!dimension too large}% + \index{Precision}\index{Floating Point Unit} Starting with version 1.2, |plot expression| uses a floating point unit. The FPU provides the full data range of scientific computing with a relative precision between $10^{-4}$ and $10^{-6}$. The |/pgf/fpu| key provides some more details. + + In case the |fpu| does not provide the desired mathematical function or is too slow\footnote{Or in case you find a bug$\dotsc$}, you should consider using the |plot gnuplot| method which invokes the external, freely available program |gnuplot| as desktop calculator. \begin{codeexample}[] \begin{tikzpicture} -\begin{semilogyaxis} -\addplot plot[id=exp,domain=0:10] - function{exp(x)}; -\end{semilogyaxis} + \begin{loglogaxis}[ + title={$\frac{1}{x^2}$}] + \addplot[blue] + expression[domain=1:1e30] + {x^-2}; + \end{loglogaxis} \end{tikzpicture} \end{codeexample} -The \meta{style options} determine the appearance of the plotted function; these parameters also affect the legend. The \meta{behavior options} 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. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{semilogyaxis}[ + title={$e^x$ logarithmically plotted}] + \addplot[blue] + expression[domain=1:700] + {exp(x)}; + \end{semilogyaxis} +\end{tikzpicture} +\end{codeexample} \end{addplotoperation} -\begin{key}{/tikz/domain=\meta{start}:\meta{end} (initially [-5:5])} +\begin{addplotoperation}[]{\marg{math expression}}{} + Use + + |\addplot |\marg{math expression}|;| + + as short-hand equivalent for + + |\addplot expression |\marg{math expression}|;| +\end{addplotoperation} + +\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{} + A variant of |\addplot expression| which allows to provide different coordinate expressions for the $x$ and $y$ coordinates. This can be used to generate parameterized plots. + + Please note that |\addplot (\x,\x^2)| is equivalent to |\addplot expression {\x^2}|. + + Note further that since the complete point expression is surrounded by round braces, you can't use round braces for either \meta{$x$ expression} or \meta{$y$ expression}. You will need to introduce curly braces additionally to round braces. +\end{addplotoperation} + +\begin{key}{/pgfplots/domain=\meta{start}:\meta{end} (initially [-5:5])} Determines the plotted range. This is not necessarily the same as the axis limits (which are configured with the |xmin|/|xmax| options). - This option is also used for plot expression, see below. -\end{key} + This option is used for |plot expression| and for |plot gnuplot|. -\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} + The |domain| key won't be used if |samples at| is specified; |samples at| has higher precedence. -\begin{key}{/tikz/prefix=\marg{file name prefix}} - A common path prefix for temporary filenames (see \cite[section~18.6]{tikz} for details). + \paragraph{Remark for \Tikz-users:} |/pgfplots/domain| and |/tikz/domain| are independent options. Please prefer the \PGFPlots\ variant (i.e. provide |domain| to an axis, |\pgfplotsset| or a plot command). Since older versions also accepted something like |\begin{tikzpicture}[domain=|$\dotsc$|]|, this syntax is also accepted as long as no \PGFPlots\ |domain| key is set. \end{key} -\begin{key}{/tikz/samples=\marg{number}} - Sets the number of sample points. -\end{key} +\begin{key}{/pgfplots/samples=\marg{number} (initially 25)} + Sets the number of sample points for |plot expression| and |plot gnuplot|. -\begin{key}{/tikz/raw gnuplot} - Disables the use of |samples| and |domain|. + The |samples| key won't be used if |samples at| is specified; |samples at| has higher precedence. + + The same special treatment of |/tikz/samples| and |/pgfplots/samples| as for the |domain| key applies here. See above for details. \end{key} -\noindent -Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction. +\begin{pgfplotskey}{samples at=\marg{coordinate list}} + Sets the $x$ coordinates for |plot expression| explicitly. This overrides |domain| and |samples|. -\begin{addplotoperation}[]{(\meta{$x$ expression},\meta{$y$ expression})}{} - Similar to |plot function|, this input method allows to provide expressions which will be sampled. But unlike |plot function|, the expressions are evaluated using the math parser of \PGF, no external program is required. -\begin{codeexample}[] -\begin{tikzpicture} -\begin{axis} - \addplot (\x,\x^2 + 4); - \addplot (\x,-5*\x^3 - \x^2); -\end{axis} -\end{tikzpicture} + The \marg{coordinate list} is a |\foreach| expression, that means it can contain a simple list of coordinates (comma--separated) but also complex |...| expressions like\footnote{Unfortunately, the |...| is somewhat restrictive when it comes to extended accuracy. So, if you have particularly small or large numbers (or a small distance), you have to provide a comma--separated list (or use the \texttt{domain} key).} +\begin{codeexample}[code only] +\pgfplotsset{samples at={5e-5,7e-5,10e-5,12e-5}} +\pgfplotsset{samples at={-5,-4.5,...,5}} +\pgfplotsset{samples at={-5,-3,-1,-0.5,0,...,5}} \end{codeexample} -The number of points and the sampled range is configured as for |plot function|, that means using |samples| and |domain|. -Please note that \PGF's math parser uses degrees for trigonometric functions: + The same special treatment of |/tikz/samples at| and |/pgfplots/samples at| as for the |domain| key applies here. See above for details. + + \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} + +\subsubsection{Computing Coordinates with Mathematical Expressions (gnuplot)} + +\begin{addplotoperation}[]{gnuplot}{\marg{gnuplot code}} +In contrast to |plot expression|, the |plot gnuplot| command employs the external program |gnuplot| to compute coordinates. The resulting coordinates are written to a text file which will be plotted with |plot file|. \PGF\ checks whether coordinates need to be re-generated and calls |gnuplot| whenever necessary (this is usually the case if you change the number of samples, the argument to |plot gnuplot| or the plotted domain\footnote{Please note that \PGFPlots\ produces slightly different files than \Tikz\ when used with |plot gnuplot| (it configures high precision output). You should use different ids to avoid conflicts in such a case.}). + +The differences between |plot expression| and |plot gnuplot| are: +\begin{itemize} + \item |plot expression| does not require any external programs and requires no additional command line options. + \item |plot expression| does not produce a lot of temporary files. + \item |plot gnuplot| uses radians for trigonometric functions while |plot expression| has degrees. + \item |plot gnuplot| is faster. + \item |plot gnuplot| has a larger mathematical library. + \item |plot gnuplot| has a higher accuracy. However, starting with version 1.2, this is no longer a great problem. The new floating point unit for \TeX\ provides reasonable accuracy and the same data range as |gnuplot|. +\end{itemize} + +Since system calls are a potential danger, they need to be enabled explicitly using command line options, for example +\begin{codeexample}[code only] +pdflatex -shell-escape filename.tex. +\end{codeexample} +Sometimes it is called |shell-escape| or |enable-write18|. Sometimes one needs two slashes -- that all depends on your \TeX\ distribution. \begin{codeexample}[] \begin{tikzpicture} \begin{axis} - \addplot plot[domain=0:360] - (\x,{sin(\x)}); +\addplot plot[id=sin] + gnuplot{sin(x)}; \end{axis} \end{tikzpicture} \end{codeexample} -the braces are necessary to delimit the $y$ argument here. If you want to use radians, use + \begin{codeexample}[] \begin{tikzpicture} -\begin{axis} - \addplot plot[domain=-3.14159:3.14159] - (\x,{sin(\x r)}); -\end{axis} +\begin{semilogyaxis} +\addplot plot[id=exp,domain=0:10] + gnuplot{exp(x)}; +\end{semilogyaxis} \end{tikzpicture} \end{codeexample} -to convert the radians to degrees. The \Tikz\ plot expression parser also accepts some more options like |samples at=|\marg{coordinate list} or |variable=\t| which are described in the \Tikz\ manual. + +The \meta{style options} determine the appearance of the plotted function; these parameters also affect the legend. The \meta{behavior options} 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. + +Please note that |plot gnuplot| does not allow per point meta data. + +Please refer to \cite[section~18.6]{tikz} for more details about |plot function| and the |gnuplot| interaction. \end{addplotoperation} +\begin{addplotoperation}[]{function}{\marg{gnuplot code}} + Use + + |\addplot function |\marg{gnuplot code}|;| + + as alias for + + |\addplot gnuplot |\marg{gnuplot code}|;| +\end{addplotoperation} + +\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} + +\begin{key}{/tikz/prefix=\marg{file name prefix}} + A common path prefix for temporary filenames (see \cite[section~18.6]{tikz} for details). +\end{key} + +\begin{key}{/tikz/raw gnuplot} + Disables the use of |samples| and |domain|. +\end{key} + + \begin{command}{\addplot+\oarg{style options} \textcolor{gray}{\dots};} Does the same like |\addplot[|\meta{style options}|] ...;| except that \meta{style options} is \emph{appended} to the arguments which would have been taken for |\addplot ...| (the element of the default list). \begin{codeexample}[] \begin{tikzpicture} \begin{axis} -\addplot (\x,{sin(\x r)}); +\addplot {sin(deg(x))}; \end{axis} \end{tikzpicture} \begin{tikzpicture} \begin{axis} -\addplot+[only marks] (\x,{sin(\x r)}); +\addplot+[only marks] {sin(deg(x))}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -451,9 +607,9 @@ It can be used to draw any \Tikz-graphics at axis coordinates. It is used like (553983, 3.053e-05) }; - \node[coordinate,pin=above:Bad!] + \node[coordinate,pin=above:{Bad!}] at (axis cs:5503,2.027e-03) {}; - \node[coordinate,pin=left:Good!] + \node[coordinate,pin=left:{Good!}] at (axis cs:187903,9.063e-05) {}; \end{loglogaxis} \end{tikzpicture} @@ -554,16 +710,16 @@ The legend appearance can be configured with the help of several styles and opti \begin{tikzpicture}[baseline] \begin{axis} \addplot+[only marks] - plot[samples=15, + expression[samples=15, error bars/y dir=both, error bars/y fixed=2.5] - (\x,3*\x+2.5*rand); + {3*x+2.5*rand}; \label{pgfplots:label1} - \addplot+[mark=none] (\x,3*\x); + \addplot+[mark=none] {3*x}; \label{pgfplots:label2} - \addplot (\x,{4*cos(\x r)}); + \addplot {4*cos(deg(x))}; \label{pgfplots:label3} \end{axis} \end{tikzpicture} @@ -598,10 +754,18 @@ Label2 = \ref{pgfplots:label2} This will also work together with |hyperref| links and |\pageref|. \end{command} +\begin{key}{/pgfplots/refstyle=\marg{label name}} + Can be used to set the \emph{styles} of a labeled, single plot. This allows to write +\begin{codeexample}[code only] +\addplot[/pgfplots/refstyle={pgfplots:label2}] +\end{codeexample} + \noindent somewhere. Please note that it may be easier to define a style with |.style|. +\end{key} + \begin{stylekey}{/pgfplots/every crossref picture} A style which will be used by the cross-referencing feature for plots. The default is \begin{codeexample}[code only] -\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em} +\pgfplotsset{every crossref picture/.style={baseline,yshift=0.3em}} \end{codeexample} \end{stylekey} @@ -615,7 +779,7 @@ Label2 = \ref{pgfplots:label2} \begin{codeexample}[] \begin{tikzpicture} \begin{axis} - \addplot (\x,\x^2+2) \closedcycle; + \addplot {x^2+2} \closedcycle; \end{axis} \end{tikzpicture} \end{codeexample} @@ -623,7 +787,7 @@ Label2 = \ref{pgfplots:label2} \begin{codeexample}[] \begin{tikzpicture} \begin{axis} - \addplot+[fill] (\x,\x^2+2) \closedcycle; + \addplot+[fill] {x^2+2} \closedcycle; \end{axis} \end{tikzpicture} \end{codeexample} @@ -679,9 +843,6 @@ The number is printed using the current number printing options, see section~\re \begin{command}{\pgfplotstabletypeset\marg{\textbackslash macro}} Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle. \end{command} -\begin{command}{\pgfplotstabletypesetfile\marg{file}} - Please refer to the manual of \PGFPlotstable, |pgfplotstable.pdf|, which is part of the \PGFPlots-bundle. -\end{command} \section{Option Reference} There are several required and even more optional arguments to modify axes. They are used like @@ -700,6 +861,45 @@ The overall appeareance can be changed with \noindent for example. There are several other styles predefined to modify the appearance, see section~\ref{sec:styles}. +\begin{command}{\pgfplotsset\marg{key-value-list}} + Defines or sets all options in \marg{key-value-list}. + + It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path. + + This command can be used to define default options for the complete document or a part of the document. For example, +\begin{codeexample}[code only] +\pgfplotsset{ + cycle list={% + {red, mark=*}, {blue,mark=*}, + {red, mark=x}, {blue,mark=x}, + {red, mark=square*}, {blue,mark=square*}, + {red, mark=triangle*}, {blue,mark=triangle*}, + {red, mark=diamond*}, {blue,mark=diamond*}, + {red, mark=pentagon*}, {blue,mark=pentagon*} + }, + legend style={ + at={(0.5,-0.2)}, + anchor=north, + legend columns=2, + cells={anchor=west}, + font=\footnotesize, + rounded corners=2pt, + }, + xlabel=$x$,ylabel=$f(x)$ +} +\end{codeexample} + can be used to set document--wise styles for line specifications, the legend's style and axis labels. + + You can also define new styles (collections of key--value--pairs) with |.style| and |.append style|. +\begin{codeexample}[code only] +\pgfplotsset{ + My Style 1/.style={xlabel=$x$, legend entries={1,2,3} }, + My Style 2/.style={xlabel=$X$, legend entries={4,5,6} } +\end{codeexample} + The |.style| and |.append style| key handlers are described in section~\ref{sec:styles} in more detail. +\end{command} + + \subsection{Pgfplots Options and \Tikz\ Options} This section is more or less technical and can be skipped unless one really wants to know more about this topic. @@ -811,15 +1011,15 @@ coordinates \begin{plottype}{jump mark left} A variant of `|const plot mark left|' which does not draw vertical lines. \begin{codeexample}[] -\begin{tikzpicture}[samples=8] -\begin{axis} +\begin{tikzpicture} +\begin{axis}[samples=8] \addplot+[jump mark left] - plot[id=parablex,domain=-5:0] - function{4*x**2 - 5}; + expression[domain=-5:0] + {4*x^2 - 5}; \addplot+[jump mark right] - plot[id=cubic,domain=-5:0] - function{0.7*x**3 + 50}; + expression[domain=-5:0] + {0.7*x^3 + 50}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -848,6 +1048,7 @@ Bar plots place horizontal or vertical bars at coordinates. Multiple bar plots i Bars are centered at plot coordinates with width |bar width|. Using bar plots usually means more than just a different way of how to connect coordinates, for example to draw ticks outside of the axis, change the legend's appearance or introduce shifts if multiple |\addplot| commands appear. There is a preconfigured style for |xbar| which is installed automatically if you provide |xbar| as argument to the axis environment which provides this functionality. +% \usetikzlibrary{patterns} \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[xbar,enlargelimits=0.15] @@ -871,7 +1072,7 @@ Here |xbar| yields |/pgfplots/xbar| because it is an argument to the axis, not t \begin{stylekey}{/pgfplots/xbar=\marg{shift for multiple plots} (default 2pt)} This style sets |/tikz/xbar| \emph{and} some commonly used options concerning horizontal bars for the complete axis. This is automatically done if you provide |xbar| as argument to an axis argument, see above. -The |xbar| style defines shifts if multiple plots are placed into one axis. If draws bars adjacent to each other, separated by \marg{shift for multiple plots}. Furthermore, it sets the style |bar cycle list| and sets tick and legend appearance options. +The |xbar| style defines shifts if multiple plots are placed into one axis. It draws bars adjacent to each other, separated by \marg{shift for multiple plots}. Furthermore, it sets the style |bar cycle list| and sets tick and legend appearance options. The style is defined as follows. \begin{codeexample}[code only] @@ -882,7 +1083,10 @@ The style is defined as follows. {\draw[##1,bar width=3pt,yshift=-0.2em,bar shift=0pt] plot coordinates {(0cm,0.8em) (2*\pgfplotbarwidth,0.6em)};}, /pgf/bar shift={% + % total width = n*w + (n-1)*skip + % -> subtract half for centering -0.5*(\numplots*\pgfplotbarwidth + (\numplots-1)*#1) + + % the '0.5*w' is for centering (.5+\plotnum)*\pgfplotbarwidth + \plotnum*#1}, /tikz/xbar}, \end{codeexample} @@ -1044,7 +1248,7 @@ Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not t \end{pgfplotsxykey} \subsubsection{Comb Plots} -Comb plots are very similar to bar plots except that they emplot single horizontal/vertical lines instead of rectangles. +Comb plots are very similar to bar plots except that they employ single horizontal/vertical lines instead of rectangles. \begin{plottype}{xcomb} \begin{codeexample}[] @@ -1071,7 +1275,7 @@ Comb plots are very similar to bar plots except that they emplot single horizont \subsubsection{Stacked Plots} \begin{pgfplotskey}{stack plots=\mchoice{x,y,false} (initially false)} - Allows stacking of plots in either $x$ or $y$ direction. Stacking means add either $x$- or $y$ coordinates of successive |\addplot| commands on top of each other. + Allows stacking of plots in either $x$ or $y$ direction. Stacking means to add either $x$- or $y$ coordinates of successive |\addplot| commands on top of each other. \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[stack plots=y] @@ -1137,10 +1341,11 @@ Comb plots are very similar to bar plots except that they emplot single horizont \end{axis} \end{tikzpicture} \end{codeexample} +The current implementation for |stack plots| does \emph{not} interpolate missing coordinates. That means stacking will fail if the plots have different grids. \end{pgfplotskey} \begin{pgfplotskey}{stack dir=\mchoice{plus,minus} (initially plus)} - Configures the direction of |stack plots|. The value |plus| will adds coordinates of successive plots while |minus| subtracts them. + Configures the direction of |stack plots|. The value |plus| will add coordinates of successive plots while |minus| subtracts them. \end{pgfplotskey} \begin{pgfplotskey}{reverse stacked plots=\mchoice{true,false} (initially true, default true)} @@ -1159,10 +1364,10 @@ Comb plots are very similar to bar plots except that they emplot single horizont \end{stylekey} \begin{stylekey}{/pgfplots/xbar interval stacked=\mchoice{plus,minus} (default plus)} - A sttyle similar to |/pgfplots/xbar stacked| for the interval based bar plot variant. + A style similar to |/pgfplots/xbar stacked| for the interval based bar plot variant. \end{stylekey} \begin{stylekey}{/pgfplots/ybar interval stacked=\mchoice{plus,minus} (default plus)} - A sttyle similar to |/pgfplots/ybar stacked| for the interval based bar plot variant. + A style similar to |/pgfplots/ybar stacked| for the interval based bar plot variant. \end{stylekey} \subsubsection{Area Plots} @@ -1187,7 +1392,7 @@ Area plots are a combination of |\closedcycle| and |stack plots|. They can be co \end{tikzpicture} \end{codeexample} \noindent -Area plots may need modified legends, for example using the |area legend| key. Furthermore, one may want to consider the |axis on top| key such that filled areas to not overlap ticks and grid lines. +Area plots may need modified legends, for example using the |area legend| key. Furthermore, one may want to consider the |axis on top| key such that filled areas do not overlap ticks and grid lines. \begin{stylekey}{/pgfplots/area style} A style which sets @@ -1311,6 +1516,223 @@ Area plots may need modified legends, for example using the |area legend| key. F \end{tikzpicture} \end{codeexample} +\subsubsection{Scatter Plots} +\label{pgfplots:scatter} +For scatter plots, the marker appearance changes for each data point. An example is that marker colors depend on the magnitude of function values $f(x)$. + +Scatter plots require ``source'' coordinates. These source coordinates can be the $y$ coordinate, or explicitly provided additional values. + +\begin{plottype}{scatter} + Enables marker appearance modifications. The default implementation acquires ``source coordinates'' for every data point (see |scatter src| below) and maps them linearly into the current color map. The resulting color is used as draw and fill color of the marker. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot+[scatter,only marks] + expression[samples=50,scatter src=y] + {x-x^2}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + The key |scatter| is simply a boolean variable which enables marker modifications. It applies only to markers and it can be combined with any other plot type. + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis} + \addplot+[scatter] + expression[samples=50,scatter src=y] + {x^3}; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\end{plottype} + +Scatter plots can be configured using a set of options. One of them is mandatory, the rest allows fine grained control over marker appearance options. + +\label{pgfplots:scatter:src} +\begin{pgfplotskey}{scatter src=\mchoice{none,x,y,z,explicit,explicit symbolic} (initially none)} + This key is necessary for any scatter plot. It needs to be provided as \marg{behavior option} for |\addplot| to configure the value used to determine marker appearances. + + The choices |x|, |y| and |z| will use either the $x$, $y$ or $z$ coordinates to determine marker options\footnote{The coordinates are used after any coordinate filters, logarithms or stacked-plot computations have been applied.}. The choice |explicit| expects the scatter source data as additional coordinate from the coordinate input streams (see section~\ref{pgfplots:providing:input} for how to provide input meta data). They will be treated as numerical data. Finally, |explicit symbolic| also expects scatter source data as additional meta information for each input coordinate, but it treats them as strings, not as numerical data. Consequently, no arithmetics is performed. It is task of the scatter plot style to do sometthing with it. See, for example, the |scatter/classes| style below. + + Please note that |scatter src|$\neq$|none| results in computational work even if |scatter=false|. +\end{pgfplotskey} + +\begin{stylekey}{/pgfplots/scatter/use mapped color=\marg{options for each marker} (initially draw=mapped color!80!black,fill=mapped color)} + This style is installed by default. When active, it recomputes the color |mapped color| for every processed point coordinate by transforming the |scatter src| coordinates into the current colormap linearly. Then, it evaluates the options provided as \marg{options for each marker} which are expected to depend on |mapped color|. + + The user interface for colormaps is described in section~\ref{pgfplots:colormap}. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[title=Default arguments] +\addplot+[scatter] + expression[scatter src=y] + {2*x+3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=Black fill color and varying draw color, + scatter/use mapped color= + {draw=mapped color,fill=black}] +\addplot+[scatter] + expression[scatter src=y] + {2*x+3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + title=Black draw color and varying fill color, + scatter/use mapped color= + {draw=black,fill=mapped color}] +\addplot+[scatter] + expression[scatter src=y] + {2*x+3}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + This key is actually a style which redefines |@pre marker code| and |@post marker code| (see below). +\end{stylekey} + +\label{pgfplots:scatterclasses} +\begin{stylekey}{/pgfplots/scatter/classes=\marg{styles for each classname}} + A scatter plot style which visualizes points using several classes. The style assumes that every point coordinate has a class label attached, that means the choice |scatter src=explicit symbolic| is assumed\footnote{If \texttt{scatter src} is not \texttt{explicit symbolic}, we expect a numeric argument which is rounded to the nearest integer. The resulting integer is used a class label. If that fails, the numeric argument is truncated to the nearest integer. If that fails as well, the point has no label.}. A class label can be a number, but it can also be a symbolic constant. Given class labels for every point, \marg{styles for each classname} contains a comma-separated list which associates appearance options to each class label. + + If you need different |scatter/classes| arguments per plot, they must be given as \marg{behavior option}, not as style option. +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[scatter/classes={ + a={mark=square*,blue},% + b={mark=triangle*,red},% + c={mark=o,draw=black,fill=black}}] + + \addplot+[scatter,only marks] + plot[scatter src=explicit symbolic] + coordinates { + (0.1,0.15) [a] + (0.45,0.27) [c] + (0.02,0.17) [a] + (0.06,0.1) [a] + (0.9,0.5) [b] + (0.5,0.3) [c] + (0.85,0.52) [b] + (0.12,0.05) [a] + (0.73,0.45) [b] + (0.53,0.25) [c] + (0.76,0.5) [b] + (0.55,0.32) [c] + }; +\end{axis} +\end{tikzpicture} +\end{codeexample} +In this example, the coordinate |(0.1,0.15)| has the associated label `|a|' while |(0.45,0.27)| has the label `|c|' (see section~\ref{sec:addplot} for details about specifying point meta data). Now, The argument to |scatter/classes| contains styles for every label -- for label `|a|', square markers will be drawn in color blue. + +In general, the format of \marg{styles for each classname} is a comma separated list of \meta{label}|=|\marg{style options}. + +\paragraph{Attention:} The keys |every mark| and |mark options| have \emph{no effect} when used inside of \marg{styles for each classname}! So, instead of assigning |mark options|, you can simply provide the options directly. They apply only to markers anyway. +\end{stylekey} + +\begin{pgfplotsxycodekeylist}{ + scatter/@pre marker code, + scatter/@post marker code} + These two keys constitute the public low-level interface which determines the marker appearance depending on the scatter source coordinates. + + Redefining them allows fine grained control even over marker types, linestyles and colors. + + The scatter plot algorithm works as follows: +\begin{enumerate} +\item The scatter source coordinates form a data stream whose data limits are computed additionally to the axis limits. This step is skipped for |symbolic| meta data. +\item Before any markers are drawn, a linear coordinate transformation from these data limits to the interval $[0.0,1000.0]$ is initialised. +\item Every scatter source coordinate\footnote{During the evaluation, the public macros \texttt{\textbackslash pgfplotspointmeta} and \texttt{\textbackslash pgfplotspointmetarange} indicate the source coordinate and the source coordinate range in the format $a:b$ (for log--axis, they are given in fixed point representation and for linear axes in floating point).} will be transformed linearly and the result is available as macro |\pgfplotspointmetatransformed| $ \in [0.0,1000.0]$. + +The decision is thus based on per thousands of the data range. The transformation is skipped for |symbolic| meta data (and the meta data is simply contained in the mentioned macro). +\item The code of |scatter/@pre marker code| is evaluated (without arguments). +\item The standard code which draws markers is evaluated. +\item The code of |scatter/@post marker code| is evaluated (without arguments). +\end{enumerate} + The idea is to generate a set of appearance keys which depends on |\pgfplotspointmetatransformed|. Then, a call to |\scope|\oarg{generated keys} as |@pre| code and the associated |\endscope| as |@post| code will draw markers individually using \oarg{generated keys}. + +A technical example is shown below. It demonstrates how to write user defined routines, in this case a three--class system\footnote{Please note that you don't need to copy this particular example: the multiple--class example is also available as predefined style \texttt{scatter/classes}.}. +\begin{codeexample}[] +\begin{tikzpicture} +% Low-Level scatter plot interface Example: +% use three different marker classes +% 0% - 30% : first class +% 30% - 60% : second class +% 60% - 100% : third class +\begin{axis}[ +scatter/@pre marker code/.code={% + \ifdim\pgfplotspointmetatransformed pt<300pt + \def\markopts{mark=square*,fill=blue}% + \else + \ifdim\pgfplotspointmetatransformed pt<600pt + \def\markopts{mark=triangle*,fill=orange}% + \else + \def\markopts{mark=pentagon*,fill=red}% + \fi + \fi + \expandafter\scope\expandafter[\markopts] +},% +scatter/@post marker code/.code={% + \endscope +}] + +\addplot+[scatter] + expression[scatter src=y,samples=40] + {sin(deg(x))}; + +\end{axis} +\end{tikzpicture} +\end{codeexample} +Please note that |\ifdim| compares \TeX\ lengths, so the example employs the suffix |pt| for any number used in this context. That doesn't change the semantics. + +\end{pgfplotsxycodekeylist} + +\subsubsection{Interrupted Plots} +\index{Interrupted Plots}% +Sometimes it is desireable to draw parts of a single plot separately, without connection between the parts (discontinuities). There is limited support for such an application. +\label{pgfplots:interrupt} +\begin{pgfplotskey}{/pgfplots/forget plot=\marg{true,false} (initially false)} + This key tells \PGFPlots\ to add a plot without changing cycle list position and legends. This key is described in all detail on page~\pageref{pgfplots:forgetplot}. + + However, it can be used to get the interesting effect of ``interrupted plot'', so it is also discussed here: +\begin{codeexample}[width=4cm] +\begin{tikzpicture} +\begin{axis}[ + width=10cm, height=210pt, + xmin=-4.7124, xmax=4.7124, + ymin=-10, ymax=10, + xtick={-4.7124,-1.5708,...,10}, + xticklabels={$-\frac32 \pi$,$-\pi/2$,$\pi/2$,$\frac32 \pi$}, + axis x line=center,axis y line=center, + no markers, + samples=100] + +% Use gnuplot as calculator here. The first two plots won't be counted: +\addplot gnuplot[id=tan0,forget plot,domain=-1.5*pi+0.003:-0.5*pi-0.003] {tan(x)}; +\addplot gnuplot[id=tan1,forget plot,domain=-0.5*pi+0.003: 0.5*pi-0.003] {tan(x)}; +\addplot gnuplot[id=tan2, domain= 0.5*pi+0.003: 1.5*pi-0.003] {tan(x)}; +\legend{$\tan(x)$} +\end{axis} +\end{tikzpicture} +\end{codeexample} + + The interesting part is in the |\addplot| commands. The |id| is specific to the gnuplot interface (and can be omitted). The |domain| option defines separate domains for every plot part. Due to the |forget plot| key, the |cycle list| position is not updated so all three plots use the same line specification. Furthermore, only the last command affects the legend (and advances the cycle list). + + \paragraph{Remark:} The |forget plot| feature is \emph{not very sophisticated}. In particular, it has the following \textbf{restrictions}: + \begin{enumerate} + \item Besides the |cycle list| side--effect, no styles are communicated between successive plots. + \item It won't work together with |stack plots|. + \end{enumerate} +\end{pgfplotskey} + \subsection{Markers and Linestyles} \label{sec:markers}% The following options of \Tikz\ are available to plots. @@ -1395,7 +1817,9 @@ All these options have been drawn with the additional options \end{axis} \end{tikzpicture} \end{codeexample} +\end{key} +\begin{stylekey}{/pgfplots/every axis plot post (initially {})} The |every axis plot post| style can be used to overwrite parts (or all) of the drawing styles which are assigned for plots. \begin{codeexample}[] % Overwrite any cycle list: @@ -1410,7 +1834,11 @@ The |every axis plot post| style can be used to overwrite parts (or all) of the \end{axis} \end{tikzpicture} \end{codeexample} -\end{key} +\end{stylekey} + +\begin{stylekey}{/pgfplots/no markers} + A style which appends |mark=none| to |every axis plot post|, which disables markers for every plot (even if the cycle list contains markers). +\end{stylekey} \begin{key}{/tikz/mark options=\marg{options}} Resets |every mark| to \marg{options}. @@ -1456,7 +1884,15 @@ The following line styles are predefined in \Tikz. \begin{stylekey}{/tikz/loosely dashed} \showit{style=loosely dashed} \end{stylekey} -You may need the option |mark options={solid}| to avoid dotted or dashed marker boundaries. +\noindent since these styles apply to markers as well, you may want to consider using +\begin{codeexample}[code only] +\pgfplotsset{ + every mark/.append style={solid} +} +\end{codeexample} +\noindent in marker styles. + +Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details. \endgroup \subsubsection{Font Size and Line Width} @@ -1467,7 +1903,7 @@ Often, one wants to change line width and font sizes for plots. This can be done \end{key} \begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)} - Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so you may need to override the styles |every tick| and |every axis grid|. + Sets the line width. Please note that line widths for tick lines and grid lines are predefined, so it may be necessary to override the styles |every tick| and |every axis grid|. The |line width| key is changed quite often in \Tikz. You should use \begin{codeexample}[code only] @@ -1477,7 +1913,7 @@ Often, one wants to change line width and font sizes for plots. This can be done \begin{codeexample}[code only] \pgfplotsset{every axis/.append style={thick}} \end{codeexample} - to change the overall line width. To also adjust ticks and grid lines, you can use + to change the overall line width. To also adjust ticks and grid lines, one can use \begin{codeexample}[code only] \pgfplotsset{every axis/.append style={ line width=1pt, @@ -1509,6 +1945,7 @@ This example shows the same plots as on page~\pageref{page:plotcoords:src} (usin xlabel=\textsc{Dof}, ylabel=$L_2$ Error ] + % see above for this macro: \plotcoords \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} \end{loglogaxis} @@ -1525,6 +1962,7 @@ This example shows the same plots as on page~\pageref{page:plotcoords:src} (usin xlabel=\textsc{Dof}, ylabel=$L_2$ Error ] + % see above for this macro: \plotcoords \legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} \end{loglogaxis} @@ -1566,18 +2004,18 @@ The package |xcolor| defines a set of predefined colors, namely \begin{tikzpicture} \begin{axis}[enlarge x limits=false] \addplot[red] - plot[samples=500] (\x,{sin(\x r)}); + expression[samples=500] {sin(deg(x))}; \addplot[orange] - plot[samples=7] (\x,{sin(\x r)}); + expression[samples=7] {sin(deg(x))}; \addplot[teal,const plot] - plot[samples=14] (\x,{sin(\x r)}); + expression[samples=14] {sin(deg(x))}; \end{axis} \end{tikzpicture} \end{codeexample} -Besides predefined colors, you can \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow}. +Besides predefined colors, it is possible to \emph{mix} two (or more) colors. For example, \showcolorandname{red!30!white} contains $30\%$ of \showcolorandname{red} and $70\%$ of \showcolorandname{white}. Consequently, one can build \showcolorandname{red!70!white} to get $70\%$ red and $30\%$ white or \showcolorandname{red!10!white} for $10\%$ red and $90\%$ white. This mixing can be done with any color, \showcolorandname{red!50!green}, \showcolorandname{blue!50!yellow}. A different type of color mixing is supported, which allows to take $100\%$ of \emph{each} component. For example, \showcolorandname{rgb,2:red,1;green,1} will add $1/2$ part \showcolorandname{red} and $1/2$ part \showcolorandname{green} and we reproduced the example from above. Using the denominator~$1$ instead of~$2$ leads to \showcolorandname{rgb,1:red,1;green,1} which uses $1$ part \showcolorandname{red} and $1$ part \showcolorandname{green}. Many programs allow to select pieces between $0,\dotsc,255$, so a denominator of $255$ is useful. Consequently, \showcolorandname{rgb,255:red,231;green,84;blue,121} uses $231/255$ red, $84/255$ green and $121/255$. This corresponds to the standard RGB color $(231,84,121)$. Other examples are \showcolorandname{rgb,255:red,32;green,127;blue,43}, \showcolorandname{rgb,255:red,178;green,127;blue,43}, \showcolorandname{rgb,255:red,169;green,178;blue,43}. @@ -1597,6 +2035,36 @@ It is also possible to use RGB values, the HSV color model or the HTML color syn \noindent creates the color with $208/255$ pieces red, $178/255$ pieces green and $43$ pieces blue, specified in standard HTML notation. Please refer to the |xcolor| manual~\cite{xcolor} for more details and color models. }% +\subsubsection{Color Maps} +\label{pgfplots:colormap} +\begin{pgfplotskey}{colormap name=\marg{color map name} (initially hot)} + Changes the current color map to the already defined map named \marg{color map name}. Available standard color maps are + + \begin{tabular}{>{\ttfamily}ll} + hot & \pgfplotsshowcolormap{hot}\\ + \end{tabular} + + Colormaps can be used, for example, in scatter plots (see section~\ref{pgfplots:scatter}). + + You can use |colormap| to create new color maps (see below). +\end{pgfplotskey} + +\begin{pgfplotskey}{colormap=\marg{name}\marg{color specification}} + Defines a new colormap named \marg{name} according to \marg{color specification} and activates it using |colormap name=|\marg{name}. + + The syntax of \marg{color specification} is the same as those for \PGF\ shadings described in~\cite[VIII -- Shadings]{tikz}: it consists of a series of colors along with a length. +\begin{codeexample}[code only] +rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb(2cm)=(0,0,1); gray(3cm)=(0.3); color(4cm)=(green) +\end{codeexample} +\pgfplotsshowcolormapexample{rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb(2cm)=(0,0,1); gray(3cm)=(0.3); color(4cm)=(green)} + +\noindent The single colors are separated by semicolons `|;|'. The length describes how much of the bar is occupied by the interval. Each entry has the form \meta{color model}|(|\meta{length}|)=(|\meta{arguments}|)|. The line above means that the left end of the colormap shall have RGB components $1,0,0$, indicating $100\%$ red and $0\%$ green and blue. The next entity starts at |1cm| and describes a color with $100\%$ green. Finally, |gray| specifies a color with the same value for each, R G and B and |color| accesses predefined colors. + +The complete length of a colormap is irrelevant: it will be mapped linearly to an internal range anyway (for efficient interpolation). The only requirement is that the left end must be at |0|. + +\paragraph{Remark:} Currently, only equidistant \marg{color specification}s are supported (each interval must have the same length). +\end{pgfplotskey} + \subsubsection{Options Controlling Linestyles} \label{sec:cycle:list}% @@ -1605,26 +2073,120 @@ Allows to specify a list of plot specifications which will be used for each \hbo There are several possiblities to change it: \begin{enumerate} - \item Use one of the predefined lists, + \item Use one of the predefined lists\footnote{These lists were named \texttt{\textbackslash coloredplotspeclist} and \texttt{\textbackslash blackwhiteplotspeclist} which appeared to be unnecessarily long, so they have been renamed. The old names are still accepted, however.}, + \begin{itemize} + \item |color| (from top to bottom) \begin{codeexample}[] \begin{tikzpicture} -\begin{loglogaxis}[ - cycle list name=\coloredplotspeclist] -\plotcoords -\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} -\end{loglogaxis} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=color] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} \end{tikzpicture} \end{codeexample} -These examples employs the same coords as in the example on page~\pageref{page:plotcoords:src}. + + \item |exotic| (from top to bottom) \begin{codeexample}[] \begin{tikzpicture} -\begin{loglogaxis}[ - cycle list name=\blackwhiteplotspeclist] -\plotcoords -\legend{$d=2$,$d=3$,$d=4$,$d=5$,$d=6$} -\end{loglogaxis} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=exotic] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} \end{tikzpicture} \end{codeexample} + + \item |black white| (from top to bottom) +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + stack plots=y,stack dir=minus, + cycle list name=black white] +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\addplot coordinates {(0,1) (0.5,1) (1,1)}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + \end{itemize} + +These predefined cycle lists habe been created with +\begin{codeexample}[code only] +\pgfplotscreateplotcyclelist{color}{% + blue,every mark/.append style={fill=blue!80!black},mark=*\\% + red,every mark/.append style={fill=red!80!black},mark=square*\\% + brown!60!black,every mark/.append style={fill=brown!80!black},mark=otimes*\\% + black,mark=star\\% + blue,every mark/.append style={fill=blue!80!black},mark=diamond*\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\% + brown!60!black,densely dashed,every mark/.append style={ + solid,fill=brown!80!black},mark=square*\\% + black,densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\% + blue,densely dashed,mark=star,every mark/.append style=solid\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\% +} +\pgfplotscreateplotcyclelist{black white}{% + every mark/.append style={fill=gray},mark=*\\% + every mark/.append style={fill=gray},mark=square*\\% + every mark/.append style={fill=gray},mark=otimes*\\% + mark=star\\% + every mark/.append style={fill=gray},mark=diamond*\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=*\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=square*\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=otimes*\\% + densely dashed,every mark/.append style={solid},mark=star\\% + densely dashed,every mark/.append style={solid,fill=gray},mark=diamond*\\% +} +\pgfplotscreateplotcyclelist{exotic}{% + teal,every mark/.append style={fill=teal!80!black},mark=*\\% + orange,every mark/.append style={fill=orange!80!black},mark=square*\\% + cyan!60!black,every mark/.append style={fill=cyan!80!black},mark=otimes*\\% + red!70!white,mark=star\\% + lime!80!black,every mark/.append style={fill=lime},mark=diamond*\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=*\\% + yellow!60!black,densely dashed, + every mark/.append style={solid,fill=yellow!80!black},mark=square*\\% + black,every mark/.append style={solid,fill=gray},mark=otimes*\\% + blue,densely dashed,mark=star,every mark/.append style=solid\\% + red,densely dashed,every mark/.append style={solid,fill=red!80!black},mark=diamond*\\% +} +\end{codeexample} + \item Provide the list explicitly, \begin{codeexample}[] \begin{tikzpicture} @@ -1645,7 +2207,7 @@ These examples employs the same coords as in the example on page~\pageref{page:p (This example list requires |\usetikzlibrary{plotmarks}|). \item Define macro names and use them with `|cycle list name|': \begin{codeexample}[code only] -\pgfcreateplotcyclelist{\mylist}{% +\pgfplotscreateplotcyclelist{mylist}{% {blue,mark=*}, {red,mark=square}, {dashed,mark=o}, @@ -1653,7 +2215,7 @@ These examples employs the same coords as in the example on page~\pageref{page:p {brown!60!black,mark options={fill=brown!40},mark=otimes*}} } ... -\begin{axis}[cycle list name=\mylist] +\begin{axis}[cycle list name=mylist] ... \end{axis} \end{codeexample} @@ -1673,21 +2235,21 @@ These examples employs the same coords as in the example on page~\pageref{page:p ... \end{axis} \end{codeexample} -In this case, the \emph{last} entry also needs a terminating `|\\|', but you can omit braces around the single entries. +In this case, the \emph{last} entry also needs a terminating `|\\|', but one can omit braces around the single entries. \end{pgfplotskeylist} \subsection{Axis Descriptions} -Axis descriptions are labels for $x$ and $y$ axis and titles. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. Their placement is always relative to the axis rectangle, where $(0,0)$ refers to the lower left corner and $(1,1)$ refers to the upper right one. +Axis descriptions are labels for $x$ and $y$ axis and titles. Axis descriptions are drawn after the plot is finished and they are not subjected to clipping. Their placement is always \emph{relative to the axis rectangle}, where $(0,0)$ refers to the lower left corner and $(1,1)$ refers to the upper right one. Furthermore, axis descriptions can be placed using the predefined node |current axis|. At the time when axis descriptions are drawn, all anchors which refer to the axis origin (that means the ``real'' point $(0,0)$) or any of the axis corners can be references using |current axis.|\meta{anchor name}. Please see section~\ref{pgfplots:sec:align}, Alignment, for further details. \subsubsection{Labels} \begin{pgfplotsxykey}{\x label=\marg{text}} -The options |xlabel| and |ylabel| change axis labels to \marg{text} which is any \TeX\ text. Use ``|xlabel={, = characters}|'' if you need to include `|=|' or `|,|' literally. +The options |xlabel| and |ylabel| change axis labels to \marg{text} which is any \TeX\ text. Use ``|xlabel={, = characters}|'' if characters like `|=|' or `|,|' need to be included literally. Labels are \Tikz-Nodes which are placed with \begin{codeexample}[code only] @@ -1712,7 +2274,7 @@ The default styles are xshift=-35pt, rotate=90}} \end{codeexample} -Whenever possible, you should use |.append style| instead of overwriting the default styles to ensure compatibility with future versions. +Whenever possible, consider using |.append style| instead of overwriting the default styles to ensure compatibility with future versions. \begin{codeexample}[code only] \pgfplotsset{every axis label/.append style={...}} \pgfplotsset{every axis x label/.append style={...}} @@ -1789,7 +2351,7 @@ As all other axis descriptions, the code can use $(0,0)$ to access the lower lef }}} \begin{tikzpicture} \begin{axis} - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -1801,12 +2363,12 @@ As all other axis descriptions, the code can use $(0,0)$ to access the lower lef Legends can be generated in two ways: the first is to use |\addlegendentry| or |\legend| inside of an axis. This method has been presented in section~\ref{pgfplots:sec:legendcmds}, Legend Commands. The other method is to use a key. \begin{pgfplotskey}{legend entries=\marg{comma separated list}} - This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. + This key can be used to assign legend entries just like the commands |\addlegendentry| and |\legend|. Again, the positioning is relative to the axis rectangle (unless units like |cm| or |pt| are specified explicitly). \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[legend entries={$x$,$x^2$}] - \addplot (\x,\x); - \addplot (\x,\x^2); + \addplot {x}; + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -1815,12 +2377,13 @@ Legends can be generated in two ways: the first is to use |\addlegendentry| or | \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[legend entries={$x$,$x^2$}] - \addplot (\x,\x); - \addplot (\x,\x^2); + \addplot {x}; + \addplot {x^2}; \legend{$a$,$b$}% overrides the option \end{axis} \end{tikzpicture} \end{codeexample} + Please be careful with whitespaces in \marg{comma separated list}: they will contribute to legend entries. Consider using `|%|' at the end of each line in multiline arguments (the end of line character is also a whitespace in \TeX). \end{pgfplotskey} {% @@ -1840,7 +2403,7 @@ will draw it at the lower left corner of the axis while \end{codeexample} means the upper right corner. The `|anchor|' option determines which point \emph{of the legend} will be placed at $(0,0)$ or $(1,1)$. -The legend is a \Tikz-matrix, so you can use any \Tikz\ option which affects +The legend is a \Tikz-matrix, so one can use any \Tikz\ option which affects nodes and matrizes (see~\cite[section 13~and~14]{tikz}). The matrix is created by something like \begin{codeexample}[code only] \matrix[style=every axis legend] { @@ -1879,7 +2442,7 @@ Use |legend columns=|\marg{number} to configure the number of horizontal legend \end{tikzpicture} \end{codeexample} \noindent -Instead of the |.append style|, you can also use |legend style| as in the following example. It has the same effect. +Instead of the |.append style|, it is possible to use |legend style| as in the following example. It has the same effect. \begin{codeexample}[] \begin{tikzpicture} @@ -1914,6 +2477,8 @@ Whenever possible, consider using |.append style| to keep the default styles act \end{codeexample} \end{stylekey} +\pgfplotsshortstylekey legend style=every axis legend\pgfeov + } \begin{pgfplotskey}{legend columns=\marg{number} (default 1)} @@ -1953,6 +2518,7 @@ The default is \end{codeexample} \begin{codeexample}[] +% \usetikzlibrary{patterns} \begin{tikzpicture} \begin{axis}[area legend, axis x line=bottom, @@ -1963,13 +2529,13 @@ The default is axis on top,xmin=0] \addplot[pattern=crosshatch dots, pattern color=blue,draw=blue] -plot[samples=500] - (\x,{sqrt(\x)}) \closedcycle; +expression[samples=500] + {sqrt(x)} \closedcycle; \addplot[pattern=crosshatch, pattern color=blue!30!white, draw=blue!30!white] - (\x,\x^2) \closedcycle; +expression {x^2} \closedcycle; \addplot[red] coordinates {(0,0) (1,1)}; \legend{$\sqrt x$,$x^2$,$x$} @@ -2015,8 +2581,8 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas xlabel=$x$,ylabel=$\sin x$] \addplot[blue,mark=none] - plot[id=sinneg,domain=-10:0,samples=40] - function{sin(x)}; + expression[domain=-10:0,samples=40] + {sin(deg(x))}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2030,8 +2596,8 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas xlabel=$x$,ylabel=$\sin x$ ] \addplot[blue,mark=none] - plot[id=sinneg,domain=-10:0,samples=40] - function{sin(x)}; + expression[domain=-10:0,samples=40] + {sin(deg(x))}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2044,8 +2610,8 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas xlabel=$x$,ylabel=$\sqrt{|x|}$ ] \addplot[blue,mark=none] - plot[id=sqrtabsx,domain=-4:4,samples=501] - function{sqrt(abs(x))}; + expression[domain=-4:4,samples=501] + {sqrt(abs(x))}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2058,9 +2624,9 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas axis x line=middle, xlabel=$x$,ylabel=$\sin x$ ] - \addplot[blue,mark=none] - plot[domain=-5:5,samples=40] - (\x,{sin(\x r)}); + \addplot[smooth,blue,mark=none] + [domain=-5:5,samples=40] + {sin(deg(x))}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2073,9 +2639,9 @@ Feel free to overwrite these styles if the default doesn't fit your needs or tas axis x line=middle, xlabel=$x$,ylabel=$\sin x$ ] - \addplot[blue,mark=none] - plot[domain=-5:5,samples=40] - (\x,{sin(\x r)}); + \addplot[smooth,blue,mark=none] + [domain=-5:5,samples=40] + {sin(deg(x))}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2099,7 +2665,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea {|->>}, xlabel=$x$,ylabel=$y^3$ ] -\addplot[blue] plot[domain=-3:5] (\x,\x^3); +\addplot[blue] expression[domain=-3:5] {x^3}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2119,7 +2685,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea \addplot[blue] plot[id=DoG, samples=100, domain=-15:15] - function{1.3*exp(-x**2/10) - exp(-x**2/20)}; + gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2130,7 +2696,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea Both cases have their advantages and disadvantages, I fear there is no reasonable default (suggestions are welcome). - The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, you will see unsatisfactory edges. + The case |separate axis lines=true| allows to draw arrow heads on each single axis line, but it can't close edges very well -- in case of thick lines, unsatisfactory edges occur. \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[ @@ -2140,10 +2706,14 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea every outer y axis line/.append style= {-stealth,green!30!black}, ] -\addplot[blue] plot[id=DoG, +\addplot[blue] + expression[ samples=100, domain=-15:15] - function{1.3*exp(-x**2/10) - exp(-x**2/20)}; + {1.3*exp(0-x^2/10) - exp(0-x^2/20)}; + % Unfortunately, there is a bug in PGF 2.00 + % something like exp(-10^2) + % must be written as exp(0-10^2) :-( \end{axis} \end{tikzpicture} \end{codeexample} @@ -2161,7 +2731,7 @@ In case |middle|, the style |every inner axis x line| allows to adjust the appea \addplot[blue] plot[id=DoG, samples=100, domain=-15:15] - function{1.3*exp(-x**2/10) - exp(-x**2/20)}; + gnuplot{1.3*exp(-x**2/10) - exp(-x**2/20)}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2215,7 +2785,7 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam axis y line=left, xlabel=$x$, ylabel=First ordinate] - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \begin{axis}[ @@ -2224,11 +2794,11 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam axis y line=right, axis x line=none, ylabel=Second ordinate] - \addplot[red] (\x,3*\x); + \addplot[red] {3*x}; \end{axis} \end{tikzpicture} \end{codeexample} -\noindent The basic idea is to draw two axis ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. This requires attention in the following possibly non-obvious aspects: +\noindent The basic idea is to draw two axis ``on top'' of each other -- one, which contains the $x$ axis and the left $y$ axis, and one which has \emph{only} the right $y$ axis. Since \PGFPlots\ does not really know what it's doing here, user attention in the following possibly non-obvious aspects is required: \begin{enumerate} \item Scaling. You should set |scale only axis| because this forces equal dimensions for both axis, without respecting any labels. \item Same $x$ limits. You should set those limits explicitly. @@ -2244,7 +2814,7 @@ It is also possible to use only the axis, without any plots: axis y line=left, xlabel=$x$, ylabel=Absolute] - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \begin{axis}[ @@ -2300,13 +2870,40 @@ The description applies |axis y discontinuity| as well, with interchanged meanin ymin=95, enlargelimits=false ] \addplot[blue,mark=none] - plot[id=square,domain=-4:4,samples=20] - function{x*x+x+104}; + expression[domain=-4:4,samples=20] + {x*x+x+104}; \end{axis} \end{tikzpicture} \end{codeexample} \end{pgfplotsxykey} +A problem might occur with the placement of the ticks on the axis. +This can be solved by specifying the minimum or maximum axis value for which a tick will be placed. + +\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord} (default axis limits), \x tickmax=\marg{coord} (default axis limits)} +\label{key:xytickminmax} +The options |xtickmin|, |xtickmax| and |ytickmin|, |ytickmax| allow to define the axis tick limits, i.e. the axis values before respectively after no ticks will be placed. +Everything outside of the axis tick limits will be not drawn. +Their default values are equal to the axis limits. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + axis x line=bottom, + axis y line=center, + tick align=outside, + axis y discontinuity=crunch, + xtickmax=3, + ytickmin=110, + ymin=95, enlargelimits=false +] + \addplot[blue,mark=none] + plot[domain=-4:4,samples=20] + expression{x*x+x+104}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotsxykeylist} \begin{pgfplotsxykey}{hide \x\ axis=\mchoice{true,false} (initially false)} Allows to hide either the $x$ or the $y$ axis. No outer rectangle, no tick marks and no labels will be drawn. Only titles and legends will be processed as usual. @@ -2317,8 +2914,8 @@ Axis scaling and clipping will be done as if you did not use |hide x axis|. \begin{axis}[ hide x axis, hide y axis, - title={$\cos(x)$}] - \addplot (\x,{cos(\x)*\x^2}); + title={$x^2\cos(x)$}] + \addplot {cos(x)*x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2328,8 +2925,8 @@ Axis scaling and clipping will be done as if you did not use |hide x axis|. \begin{axis}[ hide x axis, axis y line=left, - title={$\cos(x)$}] - \addplot (\x,{cos(\x)*\x^2}); + title={$x^2\cos(x)$}] + \addplot {cos(x)*x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2386,17 +2983,53 @@ If |scale only axis| is enabled, label, tick and legend dimensions won't influen If |scale only axis=false| (the default), \PGFPlots\ will try to produce the desired width \emph{including} labels, titles and ticks. \end{pgfplotskey} -\begin{pgfplotsxykey}{\x=\marg{dimen}} -Sets the unit size for one $x$ (or $y$) coordinate to \marg{dimen}. - - Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option. +\begin{pgfplotsxykeylist}{ + \x=\marg{dimen}, + \x={\{(\meta{x},\meta{y})\}}} +Sets the unit vectors for $x$ (or $y$). Every logical plot coordinate $(x,y)$ is drawn at the position +\[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix}. \] +The unit vectors $e_x$ and $e_y$ determine the paper position in the current (always two dimensional) image. + +The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$. +Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. It is allowed to specify a negative \marg{dimen}. \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[x=1cm,y=1cm] -\addplot plot[domain=0:3] (\x,2*\x); +\addplot expression[domain=0:3] {2*x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x=1cm,y=-0.5cm] +\addplot expression[domain=0:3] {2*x}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + +The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})^T$ explicitly\footnote{Please note that you need extra curly braces around the vector. Otherwise, the comma will be interpreted as separator for the next key-value pair.}; the corresponding |y| key works similiarly. This allows to define skewed or rotated axes. + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[x={(1cm,0.1cm)},y=1cm] +\addplot expression[domain=0:3] {2*x}; \end{axis} \end{tikzpicture} \end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + x={(5pt,1pt)}, + y={(-4pt,4pt)}] +\addplot {1-x^2}; +\end{axis} +\end{tikzpicture} +\end{codeexample} + + Setting $x$ explicitly overrides the |width| option. Setting $y$ explicitly overrides the |height| option. + Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$. Please note that it is \emph{not} possible to specify |x| as argument to |tikzpicture|. The option @@ -2408,7 +3041,75 @@ Sets the unit size for one $x$ (or $y$) coordinate to \marg{dimen}. \end{tikzpicture} \end{codeexample} won't have any effect because an axis rescales its coordinates (see the |width| option). -\end{pgfplotsxykey} + +\paragraph{Limitations:} Unfortunately, skewed axes are \textbf{not available for bar plots}. +\index{Errors!Skewed axes and bar plots}% +\index{Bar Plots!Skewed axes problems}% +\end{pgfplotsxykeylist} + +\begin{pgfplotskey}{axis equal=\marg{true,false} (initially false)} + Each unit vector is set to the same length while the axis dimensions stay constant. Afterwards, the size ratios for each unit in $x$ and $y$ will be the same. + + Axis limits will be enlarge to compensate for the scaling effect. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[axis equal=false] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{axis}[axis equal=true] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[axis equal=false] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{loglogaxis}[axis equal=true] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} + +\begin{pgfplotskey}{axis equal image=\marg{true,false} (initially false)} + Similar to |axis equal|, but the axis limits will stay constant as well (leading to smaller images). +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[axis equal image=false] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{axis}[axis equal image=true] + \addplot[blue] expression[domain=0:2*pi,samples=300] {sin(deg(x))*sin(2*deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[axis equal image=false] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\hspace{1cm} +\begin{tikzpicture} + \begin{loglogaxis}[axis equal image=true] + \addplot expression[domain=1:10000] {x^-2}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} +\end{pgfplotskey} \subsection{Error Bars} \label{sec:errorbars} @@ -2456,7 +3157,7 @@ coordinates { \pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} \begin{codeexample}[] -\pgfplotstabletypesetfile{pgfplots.testtable2.dat} +\pgfplotstabletypeset{pgfplots.testtable2.dat} \begin{tikzpicture} \begin{loglogaxis} @@ -2547,7 +3248,7 @@ Allows to change the default drawing commands for error bars. The two arguments \item the target point, $(\tilde x,\tilde y)$. \end{itemize} Both are determined by \PGFPlots\ according to the options described above. The default code is -\begin{codeexample}[code only][basicstyle=\footnotesize\ttfamily] +\begin{codeexample}[code only] /pgfplots/error bars/draw error bar/.code 2 args={% \pgfkeysgetvalue{/pgfplots/error bars/error mark}% {\pgfplotserrorbarsmark}% @@ -2564,7 +3265,7 @@ Both are determined by \PGFPlots\ according to the options described above. The \subsubsection{Input Formats of Error Coordinates} \label{sec:errorbar:input}% -Error bars with explicit error estimations for single data points require some sort of input format. This applies to `|error bars/|\meta{[xy]}| explizit|' and `|error bars/|\meta{[xy]}| explizit relative|'. +Error bars with explicit error estimations for single data points require some sort of input format. This applies to `|error bars/|\meta{[xy]}| explicit|' and `|error bars/|\meta{[xy]}| explicit relative|'. Error bar coordinates can be read from `|plot coordinates|' or from `|plot table|'. The inline plot coordinates format is \begin{codeexample}[code only] @@ -2681,25 +3382,24 @@ where the `|log plot exponent style|' allows to change number formatting options \begin{pgfplotskey}{log plot exponent style=\marg{key-value-list}} Allows to configure the number format of log plot exponents. This style is installed just before `|log base 10 number format code|' will be invoked. Please note that this style will be installed within the default code for `|log number format code|'. \begin{codeexample}[] -\tikzset{samples=15} -\pgfplotsset{every axis/.append style={ - width=7cm, - xlabel=$x$, - ylabel=$f(x)$, - extra y ticks={45}, - legend style={at={(0.03,0.97)}, - anchor=north west}}} +\pgfplotsset{ + samples=15, + width=7cm, + xlabel=$x$, + ylabel=$f(x)$, + extra y ticks={45}, + legend style={at={(0.03,0.97)}, + anchor=north west}} \begin{tikzpicture} \begin{semilogyaxis}[ log plot exponent style/.style={ /pgf/number format/fixed zerofill, - /pgf/number format/precision=1}] + /pgf/number format/precision=1}, + domain=-5:10] - \addplot plot[id=gnuplot_exp,domain=-5:10] - function{exp(x)}; - \addplot plot[id=gnuplot_expv,domain=-5:10] - function{exp(2*x)}; + \addplot {exp(x)}; + \addplot {exp(2*x)}; \legend{$e^x$,$e^{2x}$} \end{semilogyaxis} @@ -2707,26 +3407,25 @@ Allows to configure the number format of log plot exponents. This style is insta \end{codeexample} \begin{codeexample}[] -\tikzset{samples=15} -\pgfplotsset{every axis/.append style={ - width=7cm, - xlabel=$x$, - ylabel=$f(x)$, - extra y ticks={45}, - legend style={at={(0.03,0.97)}, - anchor=north west}}} +\pgfplotsset{ + samples=15, + width=7cm, + xlabel=$x$, + ylabel=$f(x)$, + extra y ticks={45}, + legend style={at={(0.03,0.97)}, + anchor=north west}} \begin{tikzpicture} \begin{semilogyaxis}[ log plot exponent style/.style={ /pgf/number format/fixed, /pgf/number format/use comma, - /pgf/number format/precision=2}] + /pgf/number format/precision=2}, + domain=-5:10] - \addplot plot[id=gnuplot_exp,domain=-5:10] - function{exp(x)}; - \addplot plot[id=gnuplot_expv,domain=-5:10] - function{exp(2*x)}; + \addplot {exp(x)}; + \addplot {exp(2*x)}; \legend{$e^x$,$e^{2x}$} \end{semilogyaxis} @@ -2734,51 +3433,6 @@ Allows to configure the number format of log plot exponents. This style is insta \end{codeexample} \end{pgfplotskey} -%-------------------------------------------------- -% \subsubsection{Defining Own Display Styles} -% You can define own display styles, although this may require some insight into \TeX-programming. Here are two examples: -% \begin{enumerate} -% \item A new fixed point display style: The following code defines a new style named `\texttt{my own fixed point style}' which uses $1{\cdot}00$ instead of $1.00$. -% \begin{lstlisting} -% \def\myfixedpointstyleimpl#1.#2\relax{% -% #1{\cdot}#2% -% }% -% \def\myfixedpointstyle#1{% -% \pgfutilensuremath{% -% \ifpgfmathfloatroundhasperiod -% \expandafter\myfixedpointstyleimpl#1\relax -% \else -% #1% -% \fi -% }% -% } -% \pgfkeys{/my own fixed point style/.code={% -% \let\pgfmathprintnumber@fixed@style=\myfixedpointstyle} -% }% -% \end{codeexample} -% You only need to overwrite the macro |\pgfmathprintnumber@fixed@style|. This macro takes one argument (the result of any numerical computations). The \TeX-boolean |\ifpgfmathfloatroundhasperiod| is true if and only if the input number contains a period. -% -% \item An example for a new scientific display style: -% \begin{lstlisting} -% % #1: -% % 0 == '0' (the number is +- 0.0), -% % 1 == '+', -% % 2 == '-', -% % 3 == 'not a number' -% % 4 == '+ infinity' -% % 5 == '- infinity' -% % #2: the mantisse -% % #3: the exponent -% \def\myscistyle#1#2e#3\relax{% -% ... -% } -% \pgfkeys{/my own sci style/.code={% -% \let\pgfmathfloatrounddisplaystyle=\myscistyle}, -% }% -% \end{codeexample} -% \end{enumerate} -%-------------------------------------------------- - @@ -2789,13 +3443,13 @@ The options |xmin|, |xmax| and |ymin|, |ymax| allow to define the axis limits, i Each missing limit will be determined automatically. -If $x$-limits have been specified explicitly and $y$-limits are computed automatically, the automatic computation of $y$-limits will only considers points which fall into the specified $x$-range (and vice--versa). The same holds true if, for example, only |xmin| has been provided explicitly: in that case, |xmax| will be updated only for points for which $x \ge $|xmin| holds. This feature can be disable using |clip limits=false|. +If $x$-limits have been specified explicitly and $y$-limits are computed automatically, the automatic computation of $y$-limits will only considers points which fall into the specified $x$-range (and vice--versa). The same holds true if, for example, only |xmin| has been provided explicitly: in that case, |xmax| will be updated only for points for which $x \ge $|xmin| holds. This feature can be disabled using |clip limits=false|. Axis limits can be increased automatically using the |enlargelimits| option. \begin{codeexample}[] \begin{tikzpicture} \begin{axis} - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2803,7 +3457,7 @@ Axis limits can be increased automatically using the |enlargelimits| option. \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[xmin=0] - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2811,7 +3465,7 @@ Axis limits can be increased automatically using the |enlargelimits| option. \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[ymax=10] - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2846,12 +3500,13 @@ A small value of |enlarge x limits| may avoid problems with large markers near t \end{stylekey} \begin{environment}{{pgfplotsinterruptdatabb}} +\index{Bounding Box Control!Disable \protect\emph{data} bounding box modifications} Everything in \marg{environment contents} will not contribute to the data bounding box. \end{environment} \subsection{Tick and Grid Options} -\begin{pgfplotsxykey}{\x tick=\mchoice{\textbackslash empty,data,\marg{coordinate list}} (initially \marg{})} +\begin{pgfplotsxykey}{\x tick=\mchoice{\textbackslash empty,data,\normalfont\marg{coordinate list}} (initially \marg{})} The options |xtick| and |ytick| assigns a list of \emph{Positions} where ticks shall be placed. The argument is either the command |\empty|, |data| or a list of coordinates. The choice |\empty| will result in no tick at all. The special value |data| will produce tick marks at every coordinate of the first plot. Otherwise, tick marks will be placed at every coordinate in \marg{coordinate list}. If this list is empty, \PGFPlots\ will compute a default list. \marg{coordinate list} will be used inside of a |\foreach \x in |\marg{coordinate list} statement. The format is as follows: @@ -2861,11 +3516,13 @@ The options |xtick| and |ytick| assigns a list of \emph{Positions} where ticks s \item |{0,2,...,10}| (the same as |{0,2,4,6,8,10}|), \item |{9,...,3.5}| (the same as |{9, 8, 7, 6, 5, 4}|), \item See \cite[Section~34]{tikz} for a more detailed definition of the options. + \item Please be careful with whitespaces inside of \marg{coordinate list} (at least around the dots). \end{itemize} For logplots, \PGFPlots\ will apply $\log(\cdot)$ to each element in `\marg{coordinate list}'. \begin{codeexample}[] \begin{tikzpicture} \begin{loglogaxis}[xtick={12,9897,1468864}] + % see above for this macro: \plotcoords \end{loglogaxis} \end{tikzpicture} @@ -2911,7 +3568,7 @@ or \end{codeexample} Please prefer the `|.append style|' versions whenever possible to ensure compatibility with future versions. -This style commands can be used at any time. The tick line width can be configured with `|major tick length|' and `|minor tick length|'. +These style commands can be used at any time. The tick line width can be configured with `|major tick length|' and `|minor tick length|'. \begin{codeexample}[] \begin{tikzpicture} @@ -2950,8 +3607,8 @@ This style commands can be used at any time. The tick line width can be configur \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[minor tick num=1] - \addplot (\x,\x^3); - \addplot (\x,-20*\x); + \addplot {x^3}; + \addplot {-20*x}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2959,8 +3616,8 @@ This style commands can be used at any time. The tick line width can be configur \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[minor tick num=3] - \addplot (\x,\x^3); - \addplot (\x,-20*\x); + \addplot {x^3}; + \addplot {-20*x}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2975,8 +3632,8 @@ This style commands can be used at any time. The tick line width can be configur \begin{tikzpicture} \begin{axis}[minor x tick num=1, minor y tick num=3] - \addplot (\x,\x^3); - \addplot (\x,-20*\x); + \addplot {x^3}; + \addplot {-20*x}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -2999,7 +3656,7 @@ Adds \emph{additional} tick positions and tick labels to the $x$~or~$y$ axis. `A rotate=90,anchor=east}}, extra x tick labels={Cut}, ] - \addplot (\x,{exp(\x)}); + \addplot {exp(x)}; \addlegendentry{$e^x$} \end{axis} \end{tikzpicture} @@ -3051,7 +3708,7 @@ They are affected by |major tick length| or options like |grid=major|. \end{pgfplotsxykey} \begin{pgfplotskeylist}{ - space between ticks=\marg{number} (initially 35), + max space between ticks=\marg{number} (initially 35), try min ticks=\marg{number} (initially 4), try min ticks log=\marg{number} (initially 3)} see Options |xtick| and |ytick| for a description. @@ -3070,18 +3727,18 @@ These options allow to place ticks at selected positions $10^k, k \in \text{\mar Using `|xtickten={1,2,3,4}|' is equivalent to `|xtick={1e1,1e2,1e3,1e4}|', but it requires fewer computational time and it allows to use the short syntax `|xtickten={1,...,4}|'. \begin{codeexample}[] -\begin{tikzpicture}[samples=8] +\begin{tikzpicture} \begin{semilogyaxis}[ + samples=8, ytickten={-6,-4,...,4}, domain=0:10] -% invoke gnuplot to generate coordinates: -\addplot plot[id=pow1] - function {2**(-2*x + 6)}; +\addplot {2^(-2*x + 6)}; \addlegendentry{$2^{-2x + 6}$} +% or invoke gnuplot to generate coordinates: \addplot plot[id=pow2] - function {2**(-1.5*x -3)}; + gnuplot {2**(-1.5*x -3)}; \addlegendentry{$2^{-1.5x -3}$} \end{semilogyaxis} \end{tikzpicture} @@ -3194,7 +3851,7 @@ which has the same effect as the `|every x tick label|' statement above. This is \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[x tick label as interval] - \addplot (\x,3*\x); + \addplot {3*x}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -3226,12 +3883,9 @@ which has the same effect as the `|every x tick label|' statement above. This is \label{sec:scaled:ticks}% \begin{pgfplotsxykeylist}{ - scaled \x\ ticks=\mchoice{true,false} (initially true), - scaled ticks=\mchoice{true,false} (initially true)} -Allows to factor out common exponents in tick labels. For example, if you have tick labels $20000,40000$ and $60000$, you may want to save some space and write $2,4,6$ with a separate factor `$\cdot 10^4$'. Use `|scaled ticks=true|' to enable this feature (default is |true|). - - The |scaled ticks| key is a style which simply enables scaled ticks for both, $x$ and $y$. - + scaled \x\ ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{number}},manual:{\normalfont\marg{text}\marg{tick scale code}}} (initially true), + scaled ticks=\mchoice{true,false,base 10:{\normalfont\meta{e}},real:{\normalfont\meta{number}},manual:{\normalfont\marg{text}\marg{tick scale code}\hfill}} (initially true)} +Allows to factor out common exponents in tick labels for \emph{linear axes}. For example, if you have tick labels $20000,40000$ and $60000$, you may want to save some space and write $2,4,6$ with a separate factor `$\cdot 10^4$'. Use `|scaled ticks=true|' to enable this feature. In case |true|, tick scaling will be triggered if the data range is either too large or too small (see below). \begin{codeexample}[] \begin{tikzpicture} \begin{axis}[scaled ticks=true] @@ -3255,13 +3909,102 @@ Allows to factor out common exponents in tick labels. For example, if you have t \end{axis} \end{tikzpicture} \end{codeexample} + + The |scaled ticks| key is a style which simply sets scaled ticks for both, $x$ and $y$. + + The value |base 10:|\meta{e} allows to adjust the algorithm manually. For example, |base 10:3| will divide every tick label by $10^3$: +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[scaled ticks=base 10:3, + /pgf/number format/sci subscript] + \addplot coordinates + {(-0.00001,2e12) (-0.00005,4e12) }; + \end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent Here, the \texttt{sci subscript} option simply saves space. +In general, |base 10:|$e$ will divide every tick by $10^e$. The effect +is not limited by the ``too large or too small'' decisions mentioned +above. + + The value |real:|\meta{number} allows to divide every tick by a fixed \meta{number}. + For example, the following plot is physically ranged from $0$ to $2\pi$, but the tick scaling algorithm is configured to divide every tick label by $\pi$. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + xtick={0,1.5708,...,10}, + domain=0:2*pi, + scaled x ticks={real:3.1415}, + xtick scale label code/.code={$\cdot \pi$}] + \addplot {sin(deg(x))}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + \noindent Setting |scaled ticks=real:|\meta{number} also changes the |tick scale label code| to +\begin{codeexample}[code only] +\pgfkeys{/pgfplots/xtick scale label code/.code={$\cdot \pgfmathprintnumber{#1}$}}. +\end{codeexample} + +A further -- not very useful -- example is shown below. Every $x$ tick label has been divided by $2$, every $y$ tick label by $3$. +\nobreak +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + scaled x ticks=real:2, + scaled y ticks=real:3] + \addplot {x^3}; + \node[pin=135:{$(3,9)$}] at (axis cs:3,9) {}; + \end{axis} +\end{tikzpicture} +\end{codeexample} + + Unfortunately, \meta{number} can't be evaluated with \PGF's math parser (yet) to maintain the full data range accepted by \PGFPlots. + + The last option, |scaled ticks=manual:|\marg{text}\marg{tick scale code} allows even more customization. It allows \emph{full control} over the displayed scaling label \emph{and} the scaling code: \marg{text} is used as-is inside of the tick scaling label while \marg{tick scale code} is supposed to be a one-argument-macro which scales each tick. Example: +\begin{codeexample}[] +\begin{tikzpicture} +\begin{axis}[ + % warning: the '%' signs are necessary (?) + scaled y ticks=manual:{$+65\,535$}{% + \pgfmathfloatcreate{1}{6.5535}{4}% + \pgfmathfloatsubtract{#1}{\pgfmathresult}% + }, + yticklabel style={ + /pgf/number format/fixed, + /pgf/number format/precision=1}, +] +\addplot plot coordinates { + (0, 65535) + (13, 65535) + (14, 65536) + (15, 65537) + (30, 65537) +}; +\end{axis} +\end{tikzpicture} +\end{codeexample} +\noindent The example uses |$+65\,535$| as tick scale label content. Furthermore, it defines the customized tick label formula $y - (+6.5535\cdot 10^4) = y - 65535$ to generate $y$ tick labels. + +The \marg{text} can be arbitrary. It is completely in user control. The second argument, \marg{tick scale code} is supposed to be a one-argument-macro in which |#1| is the current tick position in floating point representation. The macro is expected to assign |\pgfmathresult| (also in floating point representation). The \PGF\ manual~\cite{tikz} contains detailed documentation about its math engine (including floating point\footnote{However, that particular stuff is newer than \PGF\ $2.00$. At the time of this writing, it is only available as (public) CVS version.}). + +This feature may also be used do transform coordinates in case they can't be processed with \PGFPlots: transform them and supply a proper tick scaling method such that tick labels represent the original range. + +If \marg{text} is empty, the tick scale label won't be drawn (and no space will be occupied). + +Tick scaling does \emph{not} work for logarithmic axes. \end{pgfplotsxykeylist} -\begin{pgfplotscodekey}{tick scale label code} +\begin{pgfplotsxycodekeylist}{\x tick scale label code} Allows to change the default code for scaled tick labels. The default is \begin{codeexample}[code only] -tick scale label code/.code={$\cdot 10^{#1}$}. +xtick scale label code/.code={$\cdot 10^{#1}$}. \end{codeexample} + +If the code is empty, no tick scale label will be drawn (and no space is consumed). +\end{pgfplotsxycodekeylist} + +\begin{pgfplotscodekey}{tick scale label code} + A style which sets both, |xtick scale label code| and the corresponding variant for $y$. \end{pgfplotscodekey} \begin{pgfplotskey}{scale ticks below=\marg{exponent}} @@ -3282,7 +4025,7 @@ Allows fine tuning of the '|scaled ticks|' algorithm: if the axis limits are of \begin{pgfplotsxykey}{\x tick pos=\mchoice{left,right,both} (initially both)} Allows to choose where to place the small tick lines. In the default configuration, this does also affect tick \emph{labels}, see below. -For $y$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$. +For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$. \end{pgfplotsxykey} \begin{pgfplotskey}{tickpos=\mchoice{left,right,both}} @@ -3292,7 +4035,7 @@ For $y$, the additional choices |bottom| and |top| can be used which are equival \begin{pgfplotsxykey}{\x ticklabel pos=\mchoice{left,right,default} (initially default)} Allows to choose where to place tick \emph{labels}. The choices |left| and |right| place tick labels either at the left or at the right side of the complete axis. The choice |default| uses the same setting as |xtick pos| (or |ytick pos|). This option is only useful for boxed axis -- keep it to |default| for non-boxed figures. -For $y$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $y$. +For $x$, the additional choices |bottom| and |top| can be used which are equivalent to |left| and |right|, respectively. Both are accepted for $x$. \end{pgfplotsxykey} \begin{pgfplotskey}{ticklabelpos=\mchoice{left,right,default}} @@ -3386,6 +4129,7 @@ This example employs the coordinates defined on page~\pageref{page:plotcoords:sr ylabel={$L_2$ Error}, grid=major ] +% see above for this macro: \plotcoords \end{loglogaxis} \end{tikzpicture} @@ -3413,6 +4157,9 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn \end{codeexample} \end{pgfplotsxykeylist} +\begin{pgfplotsxykeylist}{\x tickmin=\marg{coord}, \x tickmax=\marg{coord}} + These keys can be used to modify minimum/maximum values before ticks are drawn. Because this applies to axis discontinuities, it is described on page~\pageref{key:xytickminmax} under section~\ref{key:xytickminmax}, ``Axis Discontinuities"'. +\end{pgfplotsxykeylist} @@ -3435,14 +4182,6 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn Use |\pgfplotsset{|\meta{key}|/.append style={|\meta{key-value-list}|}}| to append \marg{key-value-list} to the style \meta{key}. This will assume the prefix |/pgfplots|. \end{handler} -\begin{command}{\pgfplotsset\marg{key-value-list}} - Defines or sets all options in \marg{key-value-list}. - - It is a shortcut for |\pgfqkeys{/pgfplots}|\marg{key-value-list}, that means it inserts the prefix |/pgfplots| to any option which has no full path. - - You can define new style keys with |.style| and |.append style|, see above. -\end{command} - \subsubsection*{Styles installed for linear/logarithmic axis} \begin{stylekey}{/pgfplots/every axis (initially empty)} @@ -3469,8 +4208,6 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn \begin{stylekey}{/pgfplots/every axis plot (initially empty)} Installed for each plot. This style may contain \meta{behavior options} like samples, gnuplot parameters, error bars and it may contain \meta{style options} which affect the final drawing commands. - -% \FIXME{currently, pgfplots options need to be prefixed with /pgfplots/} \end{stylekey} \begin{stylekey}{/pgfplots/every axis plot post (initially empty)} @@ -3485,8 +4222,8 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn legend style={ at={(0.03,0.97)},anchor=north west}, domain=0:1] - \addplot (\x,\x^2); - \addplot (\x,{exp(\x)}); + \addplot {x^2}; + \addplot {exp(x)}; \legend{$x^2$,$e^x$} \end{axis} \end{tikzpicture} @@ -3494,7 +4231,11 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn \end{stylekey} \begin{stylekey}{/pgfplots/every axis plot no \# (initially empty)} - Used for every \#th plot where $\#=1,2,3,4,\dotsc$. This option may also contain \meta{behavior options}. + Used for every \#th plot where $\#=0,1,2,3,4,\dotsc$. This option may also contain \meta{behavior options}. +\end{stylekey} + +\begin{stylekey}{/pgfplots/every forget plot (initially empty)} + Used for every plot which has |forget plot| activated. This option may also contain \meta{behavior options}. \end{stylekey} \subsubsection*{Styles for axis descriptions} @@ -3503,7 +4244,7 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn Used for $x$~and~$y$ axis label. You can use `|at=|\parg{x,y} to set its position where $(0,0)$ refers to the lower left corner and $(1,1)$ to the upper right one. \end{stylekey} -\pgfplotsshortstylekey label style=every axis label; +\pgfplotsshortstylekey label style=every axis label\pgfeov \begin{xystylekey}{/pgfplots/every axis \x\ label} Used only~$x$ or only for~$y$ labels, installed after `|every axis label|'. @@ -3524,7 +4265,7 @@ Grid lines will be drawn before tick lines are processed, so ticks will be drawn \paragraph{Attention:} These styles will be overwritten by |axis x line| and/or |axis y line|. Please remember to place your modifications after the axis line variations. \end{xystylekey} -\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label; +\pgfplotsshortxystylekeys \x\ label style,\x label style=every axis \x\ label\pgfeov \begin{stylekey}{/pgfplots/every axis title} Used for any axis title. The |at=|\parg{x,y} command works as for `|every axis label|'. @@ -3535,7 +4276,7 @@ The initial setting is \end{codeexample} \end{stylekey} -\pgfplotsshortstylekey title style=every axis title; +\pgfplotsshortstylekey title style=every axis title\pgfeov \begin{stylekey}{/pgfplots/every axis legend} Installed for each legend. As for |every axis label|, the legend's position can be placed using coordinates between $0$~and~$1$, see above. @@ -3552,7 +4293,7 @@ The initial setting is \end{codeexample} \end{stylekey} -\pgfplotsshortstylekey legend style=every axis legend; +\pgfplotsshortstylekey legend style=every axis legend\pgfeov \subsubsection*{Styles for axis lines} \begin{xystylekey}{/pgfplots/every outer \x\ axis line (initially empty)} @@ -3584,19 +4325,19 @@ Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots: Installed for each of the small tick \emph{lines}. \end{stylekey} -\pgfplotsshortstylekey tick style=every tick; +\pgfplotsshortstylekey tick style=every tick\pgfeov \begin{stylekey}{/pgfplots/every minor tick (initially empty)} Used for each minor tick line, installed after `|every tick|'. \end{stylekey} -\pgfplotsshortstylekey minor tick style=every minor tick; +\pgfplotsshortstylekey minor tick style=every minor tick\pgfeov \begin{stylekey}{/pgfplots/every major tick (initially empty)} Used for each major tick line, installed after `|every tick|'. \end{stylekey} -\pgfplotsshortstylekey major tick style=every major tick; +\pgfplotsshortstylekey major tick style=every major tick\pgfeov \begin{stylekey}{/pgfplots/every tick label (initially empty)} Used for each $x$~and~$y$ tick labels. @@ -3606,7 +4347,7 @@ Please refer to section~\ref{pgfplots:page:axislines} on page~\pageref{pgfplots: Used for each $x$ (or $y$, respectively) tick label, installed after `|every tick label|'. \end{xystylekey} -\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label; +\pgfplotsshortxystylekeys \x\ tick label style,\x ticklabel style=every \x\ tick label\pgfeov \begin{xystylekey}{/pgfplots/every \x\ tick scale label} Configures placement and display of the nodes containing the order of magnitude of tick labels, see section~\ref{sec:scaled:ticks} for more information about |scaled ticks|. @@ -3619,24 +4360,24 @@ The initial settings are \end{codeexample} \end{xystylekey} -\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label; +\pgfplotsshortxystylekey \x\ tick scale label style=every \x\ tick scale label\pgfeov \begin{xystylekey}{/pgfplots/every \x\ tick (initially empty)} Installed for tick \emph{lines} on either $x$ or $y$ axis. \end{xystylekey} -\pgfplotsshortxystylekey \x\ tick style=every \x\ tick; +\pgfplotsshortxystylekey \x\ tick style=every \x\ tick\pgfeov \begin{xystylekey}{/pgfplots/every minor \x\ tick (initially empty)} Installed for minor tick lines on either $x$ or $y$ axis. \end{xystylekey} -\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick; +\pgfplotsshortxystylekey minor \x\ tick style=every minor \x\ tick\pgfeov \begin{xystylekey}{/pgfplots/every major \x\ tick (initially empty)} Installed for major tick lines on either $x$ or $y$ axis. \end{xystylekey} -\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick; +\pgfplotsshortxystylekey major \x\ tick style=every major \x\ tick\pgfeov \begin{xystylekey}{/pgfplots/every extra \x\ tick} Allows to configure the appearance of `|extra x ticks|'. This style is installed before touching the first extra $x$~tick. It is possible to set any option which affects tick or grid line generation. @@ -3656,7 +4397,7 @@ The initial setting is \end{codeexample} \end{xystylekey} -\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick; +\pgfplotsshortxystylekey extra \x\ tick style=every extra \x\ tick\pgfeov @@ -3666,37 +4407,37 @@ The initial setting is Used for each grid line. \end{stylekey} -\pgfplotsshortstylekey grid style=every axis grid; +\pgfplotsshortstylekey grid style=every axis grid\pgfeov \begin{stylekey}{/pgfplots/every minor grid (initially empty)} Used for each minor grid line, installed after `|every axis grid|'. \end{stylekey} -\pgfplotsshortstylekey minor grid style=every minor grid; +\pgfplotsshortstylekey minor grid style=every minor grid\pgfeov \begin{stylekey}{/pgfplots/every major grid (initially empty)} Likewise, for major grid lines. \end{stylekey} -\pgfplotsshortstylekey major grid style=every major grid; +\pgfplotsshortstylekey major grid style=every major grid\pgfeov \begin{xystylekey}{/pgfplots/every axis \x\ grid (initially empty)} Used for each grid line in either $x$ or $y$ direction. \end{xystylekey} -\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid; +\pgfplotsshortxystylekey \x\ grid style=every axis \x\ grid\pgfeov \begin{xystylekey}{/pgfplots/every minor \x\ grid (initially empty)} Used for each minor grid line in either $x$ or $y$ direction. \end{xystylekey} -\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid; +\pgfplotsshortxystylekey minor \x\ grid style=every minor \x\ grid\pgfeov \begin{xystylekey}{/pgfplots/every major \x\ grid (initially empty)} Used for each major grid line in either $x$ or $y$ direction. \end{xystylekey} -\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid; +\pgfplotsshortxystylekey major \x\ grid style=every major \x\ grid\pgfeov \subsubsection*{Styles for error bars} @@ -3704,7 +4445,7 @@ The initial setting is Installed for every error bar. \end{stylekey} -\pgfplotsshortstylekey error bars/error bar style=every error bar; +\pgfplotsshortstylekey error bars/error bar style=every error bar\pgfeov \subsubsection{(Re-)Defining Own Styles} \label{sec:styles:own}% @@ -3721,7 +4462,7 @@ to create own styles. If \meta{style name} exists already, it will be replaced. \end{tikzpicture} \end{codeexample} -\subsection{Alignment Options} +\subsection{Alignment Options and Bounding Box Control} \label{pgfplots:sec:align} \begin{pgfplotskey}{anchor=\marg{name} (initially south west)} @@ -3748,7 +4489,7 @@ There are four sets of anchors available: anchors positioned on the axis rectang \addplot table from{\plottable}; %\addplot coordinates {(0,0) (1,1)}; \addlegendentry{$f(x)$} - \addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] function{10000*sin(x/3)}; + \addplot[red] plot[id=gnuplot_ppp,domain=-40:40,samples=120] gnuplot{10000*sin(x/3)}; \addlegendentry{$g(x)$} \end{axis} }% @@ -3827,7 +4568,7 @@ And finally, we have origin anchors which are especially useful when axis lines every axis y label/.style={at={(current axis.above origin)},anchor=north east}, inner axis line style={->}, ] - \addplot plot[domain=-2:5] (\x,20*\x); + \addplot plot[domain=-2:5] {20*x}; \end{axis} {\pgfplotsset{every pin/.append style={pin distance=1cm}}% \showit{above origin}{45} @@ -3851,13 +4592,13 @@ The default axis anchor is |south west|, which means that the picture coordinate \tikzset{domain=-1:1} \begin{tikzpicture} \begin{axis}[xlabel=A normal sized $x$ label] - \addplot[smooth,blue,mark=*] (\x,\x^2); + \addplot[smooth,blue,mark=*] {x^2}; \end{axis} \end{tikzpicture}% \hspace{0.15cm} \begin{tikzpicture} \begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }] - \addplot[smooth,blue,mark=*] (\x,\x^2); + \addplot[smooth,blue,mark=*] {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -3866,13 +4607,13 @@ The default axis anchor is |south west|, which means that the picture coordinate \tikzset{domain=-1:1} \begin{tikzpicture}[baseline] \begin{axis}[xlabel=A normal sized $x$ label] - \addplot[smooth,blue,mark=*] (\x,\x^2); + \addplot[smooth,blue,mark=*] {x^2}; \end{axis} \end{tikzpicture}% \hspace{0.15cm} \begin{tikzpicture}[baseline] \begin{axis}[xlabel={$\displaystyle \sum_{i=0}^N n_i $ }] - \addplot[smooth,blue,mark=*] (\x,\x^2); + \addplot[smooth,blue,mark=*] {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -3921,12 +4662,70 @@ cycle list={ \end{codeexample} -\item[Bounding box restrictions] +\item[Bounding box restrictions] Bounding box restrictions can be realized with several methods of \PGF: +\begin{enumerate} + \item The |overlay| option, + \item The |pgfinterruptboundingbox| environment, + \item The |\useasboundingbox| path. +\end{enumerate} +\begin{key}{/tikz/overlay} +\index{Bounding Box Control!Excluding Image Parts} + A special key of \PGF\ which disables bounding box updates for (parts of) the image. The effect is that those parts are an ``overlay'' over the document. + + For \PGFPlots, |overlay| can be useful to position legends or other axis descriptions outside of the axis~-- without affecting its size (and without affecting alignment). + +For example, one may want to include only certain parts of the axis into the final bounding box. This would allow horizontal alignment (centering): +\begin{codeexample}[] +\begin{tikzpicture}% + \begin{axis}[ + title=A title, + ylabel style={overlay}, + yticklabel style={overlay}, + xlabel={$x$}, + ylabel={$y$}, + legend style={at={(0.5,0.97)}, + anchor=north,legend columns=-1}, + domain=-2:2 + ] + \addplot {x^2}; + \addplot {x^3}; + \addplot {x^4}; + \legend{$x^2$,$x^3$,$x^4$} + \end{axis} +\end{tikzpicture}% +\end{codeexample} +\noindent Now, the left axis descriptions ($y$ label and $y$ ticks) stick out of the bounding box. + +The following example places a legend somewhere without affecting the bounding box. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[ + domain=0:6.2832,samples=200, + legend style={ + overlay, + at={(-0.5,0.5)}, + anchor=center}, + every axis plot post/.append style={mark=none}, + enlargelimits=false] + + \addplot {sin(deg(x)+3)+rand*0.05}; + \addplot {cos(deg(x)+2)+rand*0.05}; + \legend{Signal 1,Signal 2} + \end{axis} +\end{tikzpicture} +\end{codeexample} + + More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}. +\end{key} + + \label{sec:bounding:box:example}% +\index{Bounding Box Control} +\index{Bounding Box Control!pgfinterruptboundingbox} {% -The following figure is centered and encapsulated with an |\fbox| to show its bounding box. -\setlength{\fboxsep}{0pt}% +An alternative to |overlay| is shown below: the figure has a truncated bounding box with is shown using |\fbox|. \begin{codeexample}[] +\setlength{\fboxsep}{0pt}% \fbox{% \begin{tikzpicture}% \begin{pgfinterruptboundingbox} @@ -3939,9 +4738,9 @@ The following figure is centered and encapsulated with an |\fbox| to show its bo anchor=north,legend columns=-1}, domain=-2:2 ] - \addplot (\x,\x^2); - \addplot (\x,\x^3); - \addplot (\x,\x^4); + \addplot {x^2}; + \addplot {x^3}; + \addplot {x^4}; \legend{$x^2$,$x^3$,$x^4$} \end{axis} \end{pgfinterruptboundingbox} @@ -3953,7 +4752,7 @@ The following figure is centered and encapsulated with an |\fbox| to show its bo }% \end{codeexample}% }% -The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument. +The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument (see~\cite{tikz}). \end{description} \end{pgfplotskey} @@ -3967,10 +4766,11 @@ The |pgfinterruptboundingbox| environment does not include its content into the \end{predefinednode} \begin{pgfplotskey}{at=\marg{coordinate expression}} -Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at=|\parg{x,y}. +Assigns a position for the complete axis image. This option works similarly to the |at|-option of |\node[at=|\marg{coordinate expression}|]|, see~\cite{tikz}. The common syntax is |at={|\parg{x,y}|}|. \end{pgfplotskey} \subsection{Symbolic Coordinates and User Transformations} +\label{pgfplots:sec:symbolic:coords} \PGFPlots\ supports user transformations which can be applied to input and output coordinates. Suppose the plot shall display days versus account statements over time. Then, one wants to visualize date versus credit balance. But: dates need to be transformed to numbers before doing so! Furthermore, tick labels shall be displayed as dates as well. This, and more general transformations, can be realized using the |x coord trafo| and |y coord trafo| keys. \begin{pgfplotsxycodekeylist}{ @@ -4005,7 +4805,8 @@ Assigns a position for the complete axis image. This option works similarly to t \noindent which simply disables the transformation (the same for $y$, of course). \end{pgfplotsxycodekeylist} -\subsubsection{Dates as input coordinates} +\subsubsection{Dates as Input Coordinates} +\label{pgfplots:sec:date:coords} The already mentioned application of using dates as input coordinates has been predefined. It relies on the \pgfname\ calendar library which converts dates to numbers in the julian calendar. Then, one coordinate unit is one day. \begin{tikzlibrary}{dateplot} @@ -4029,10 +4830,11 @@ The already mentioned application of using dates as input coordinates has been p A complete example (with fictional data) is shown below. \pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}} +% \usetikzlibrary{dateplot}\usepackage{eurosym} \begin{codeexample}[] % requires \usetikzlibrary{dateplot} ! -\pgfplotstabletypesetfile[string type]{plotdata/accounts.dat} +\pgfplotstabletypeset[string type]{plotdata/accounts.dat} \begin{tikzpicture} \begin{axis}[ @@ -4072,6 +4874,8 @@ where $y = \log(m)$ is computed with a newton method applied to $\exp(y) - m$. T \label{sec:disabledatascaling}% \begin{pgfplotskey}{disabledatascaling=\mchoice{true,false} (initally 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. @@ -4085,10 +4889,10 @@ So far, the data scale transformation applies only to normal axis (logarithmic s \end{pgfplotskey} -\begin{pgfplotsxykey}{\x\ filter/.code=\marg{...}} % FIXME create a xycodekey environment +\begin{pgfplotsxycodekeylist}{\x\ filter} The code keys |x filter| and |y filter| allow coordinate filtering. A coordinate filter gets an input coordinate as |#1|, applies some operation and writes the result into the macro |\pgfmathresult|. If |\pgfmathresult| is empty afterwards, the coordinate is discarded. -It is allowed if filters do not |\pgfmathresult|. In this case, the unfiltered coordinate will be used. +It is allowed if filters do not change |\pgfmathresult|. In this case, the unfiltered coordinate will be used. Coordinate filters are useful in automatic processing system, where \PGFPlots\ is used to display automatically generated plots. You may not want to filter your coordinates by hand, so these options provide a tool to do this automatically. @@ -4118,7 +4922,7 @@ During evaluation of the filter, the macro |\coordindex| contains the number of \fi \fi }] -\addplot (\x,\x^2); +\addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -4129,7 +4933,7 @@ There is also a style key which simplifies selection by index, see below. If the corresponding axis is logarithmic, |#1| is the \emph{logarithm} of the coordinate as a real number, for example |#1=4.2341|. The arguments to coordinate filters are not transformed. You may need to call coordinate parsing routines. -\end{pgfplotsxykey} +\end{pgfplotsxycodekeylist} \begin{stylekey}{/pgfplots/skip coords between index=\marg{begin}\marg{end}} A style which appends an |x filter| which discards selected coordinates. The selection is done by index where indexing starts with~$0$, see |\coordindex|. Every coordinate with index $\meta{begin} \le i < \meta{end}$ will be skipped. @@ -4140,7 +4944,7 @@ There is also a style key which simplifies selection by index, see below. skip coords between index={5}{11}, skip coords between index={15}{18}] -\addplot (\x,\x^2); +\addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -4153,13 +4957,49 @@ There is also a style key which simplifies selection by index, see below. \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. -You may use this in conjunction with |xfilter=...| to reset any counters or whatever. An example would be to change every $4$th coordinate. +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. \end{pgfplotskey} +\begin{pgfplotskey}{forget plot=\marg{true,false} (initially false)} +\label{pgfplots:forgetplot} + Allows to include plots which are not remembered for legend entries, which do not increase the number of plots and which are not considered for cycle lists. + + A forgotten plot can be some sort of decoration which has a separate style and does not influence the axis state, although it is processed as any other plot. + Please provide this option as \meta{behavior option} to |\addplot| as in the following example. +\begin{codeexample}[] +\begin{tikzpicture} + \begin{loglogaxis}[ + table/x=Basis, + table/y={L2/r}, + xlabel=Degrees of Freedom, + ylabel=relative Error, + title=New Experiments (old in gray), + legend entries={$e_1$,$e_2$,$e_3$} + ] + \addplot[black!15] plot[forget plot] + table {plotdata/oldexperiment1.dat}; + \addplot[black!15] plot[forget plot] + table {plotdata/oldexperiment2.dat}; + \addplot[black!15] plot[forget plot] + table {plotdata/oldexperiment3.dat}; + \addplot table {plotdata/newexperiment1.dat}; + \addplot table {plotdata/newexperiment2.dat}; + \addplot table {plotdata/newexperiment3.dat}; + \end{loglogaxis} +\end{tikzpicture} +\end{codeexample} + Since forgotten plots won't increase the plot index, they will use the same |cycle list| entry as following plots. This can be used to ``interrupt'' plots as is described in section~\ref{pgfplots:interrupt}. +\index{Interrupted Plots} + + The style |every forget plot| can be used to configure styles for each such plot. Please note that |every plot no |\meta{index} styles are not applicable here. + + A forgotten plot will be stacked normally if |stack plots| is enabled! +\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. \begin{codeexample}[] @@ -4172,7 +5012,7 @@ Allows to insert \marg{commands} just before the axis is ended. This option take }}} \begin{tikzpicture} \begin{axis} - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -4189,7 +5029,7 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm }}} \begin{tikzpicture} \begin{axis} - \addplot (\x,\x^2); + \addplot {x^2}; \end{axis} \end{tikzpicture} \end{codeexample} @@ -4207,7 +5047,7 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm axis on top=true, axis x line=middle, axis y line=middle] - \addplot+[fill] (\x,\x^3) \closedcycle; + \addplot+[fill] {x^3} \closedcycle; \end{axis} \end{tikzpicture} \end{codeexample} @@ -4218,9 +5058,23 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm axis on top=false, axis x line=middle, axis y line=middle] - \addplot+[fill] (\x,\x^3) \closedcycle; + \addplot+[fill] {x^3} \closedcycle; \end{axis} \end{tikzpicture} \end{codeexample} 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{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|. + However, this engine has been written to produce graphics and is not suitable for scientific computing. It is limited to fixed point numbers in the range $\pm 16384.00000$. + + If the |fpu| is enabled (|true|, the initial configuration) the high-precision floating point library of \PGF\ written by Christian Feuersänger will be used. It offers the full range of IEEE double precision computing in \TeX. This FPU is also part of \PGFPlotstable, and it is activated by default for |create col/expr| and all other predefined mathematical methods. + + Use +\begin{codeexample}[code only] +\pgfkeys{/pgf/fpu=false} +\end{codeexample} + \noindent in order to de-activate the extended precision. If you prefer using the |fp| (fixed point) package, possibly combined with Mark Wibrows corresponding \PGF\ library, the |fpu| will be deactivated automatically. Please note, however, that |fp| has a smaller data range (about $\pm 10^{17}$) and may be slower. +\end{key} |