Manual for Package pgfplots
2D/3D Plots in LATeX, Version 1.18.1
http://sourceforge.net/projects/pgfplots

\foreachvariables in list {commands}

A powerful loop command provided by TikZ, see the TikZ manual for details.

Iterating 1. Iterating 2. Iterating 3. Iterating 4.

copy \foreach \x in {1,2,...,4} {Iterating \x. }%

A pgfplots related example could be

copy \foreach \i in {1,2,...,10} {\addplot table {datafile\i}; }%

\pgfplotsforeachungroupedvariable in list {command}

A specialised variant of \foreach which can do two things: it does not introduce extra groups while executing command and it allows to invoke the math parser for (simple!) \(x_0\),\(x_1\),...,\(x_n\) expressions.

Iterating 1. Iterating 2. Iterating 3. Iterating 4. All collected = , 1, 2, 3, 4.

copy \def\allcollected{} \pgfplotsforeachungrouped \x in {1,2,...,4} {Iterating \x. \edef\allcollected{\allcollected, \x}}% All collected = \allcollected.

A more useful example might be to work with tables. The following example is taken from PgfplotsTable:

copy \pgfplotsforeachungrouped \i in {1,2,...,10} {% \pgfplotstablevertcat{\output}{datafile\i} % appends `datafile\i' -> `\output' }% % since it was ungrouped, \output is still defined (would not work % with \foreach)

Remark:

The special syntax list=\(x_0\),\(x_1\),...,\(x_n\), i.e. with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if /pgf/fpu is active. In all other cases, \pgfplotsforeachungrouped invokes \foreach and provides the results without TeX groups.

Keep in mind that inside of an axis environment, all loop constructions (including custom loops, \foreach and \pgfplotsforeachungrouped) need to be handled with care: loop arguments can only be used in places where they are immediately evaluated; but pgfplots postpones the evaluation of many macros. For example, to loop over something and to generate axis descriptions of the form \node at (axis cs:\i,0.5)..., the loop macro \i will be evaluated in \end{axis} – but at that time, the loop is over and its value is lost. The correct way to handle such an application is to expand the loop variable explicitly. For example:

The example generates three loop iterations: \i=1, \j=a; then \i=2, j=b; then \i=3, \j=c. Inside of the loop body, it expands them and assigns the result to a macro using an “expanded definition”, \edef. The result no longer contains either \i or \j (since these have been expanded). Then, it invokes the resulting macro. Details about the TeX command \edef and expansion control can be found in the document TeX-programming-notes.pdf which comes with pgfplots.

\pgfplotsinvokeforeach{list} {command}

A variant of \pgfplotsforeachungrouped (and such also of \foreach) which replaces any occurrence of #1 inside of command once for every element in list. Thus, it actually assumes that {command} is like a \newcommand body.

In other words, command is invoked for every element of list. The actual element of list is available as #1.

As \pgfplotsforeachungrouped, this command does not introduce extra scopes (i.e. it is ungrouped as well).

The difference to \foreach \x in list{command} is subtle: the \x would not be expanded whereas #1 is.

Invoke them: [a] [b] [c] [d]

copy \pgfkeys{ otherstyle a/.code={[a]}, otherstyle b/.code={[b]}, otherstyle c/.code={[c]}, otherstyle d/.code={[d]}} \pgfplotsinvokeforeach{a,b,c,d} {\pgfkeys{key #1/.style={otherstyle #1}}} Invoke them: \pgfkeys{key a} \pgfkeys{key b} \pgfkeys{key c} \pgfkeys{key d}

The counter example would use a macro (here \x) as loop argument:

Invoke them: [d] [d] [d] [d]

copy \pgfkeys{ otherstyle a/.code={[a]}, otherstyle b/.code={[b]}, otherstyle c/.code={[c]}, otherstyle d/.code={[d]}} \pgfplotsforeachungrouped \x in {a,b,c,d} {\pgfkeys{key \x/.style={otherstyle \x}}} Invoke them: \pgfkeys{key a} \pgfkeys{key b} \pgfkeys{key c} \pgfkeys{key d}

Restrictions:

you can’t nest this command yet (since it does not introduce protection by scopes).

\pgfmathparse{expression} ¶

Invokes the pgf math parser for expression and defines \pgfmathresult to be the result.

The result is ‘42.0’.

copy \pgfmathparse{1+41} The result is `\pgfmathresult'.

The math engine in pgf typically uses TeX’s internal arithmetics. That means: it is well suited for numbers in the range \([-16384,16384]\) and has a precision of \(5\) digits.

The number range is typically too small for plotting applications. pgfplots improves the number range by means of \pgfkeys{/pgf/fpu}\pgfmathparse{1+41} to activate the “floating point unit” (fpu) and to apply all following operations in floating point.

In pgfplots, the key /pgfplots/use fpu is typically on, which means that any coordinate arithmetics are carried out with the fpu. However, all pgf related drawing operations still use the standard math engine.

In case you ever need to process numbers of extended precision, you may want to use

The result is ‘1 · 106 ’.

copy \pgfkeys{/pgf/fpu}% \pgfmathparse{1000*1000} The result is `\pgfmathprintnumber{\pgfmathresult}'.

Note that results of the fpu are typically not in human-readable format, so \pgfmathprintnumber is the preferred way to typeset such numbers.

Please refer to the PGF/TikZ manual for more details.

/pgfplots/use fpu=true|false (initially true) ¶

pgfplots comes with different approaches to compute math expressions and use fpu is the most powerful. It implements math operations either in the lua backend or in a pure TeX implementation and comes with a high number range and adequate precision.

However, the values stored in \pgfmathresult are cryptic and need to be processed by means of special macros. The switch use fpu is only useful if this number format results in difficulties, i.e. it is a debug switch which should never be used in normal operations.

/pgf/declare function=function definitions ¶

Allows to define one or more functions.

The argument function definitions can contain one or more definitions, and each must be terminated by a semicolon:



copy % Preamble: \pgfplotsset{width=7cm,compat=1.18} \begin{tikzpicture} \begin{axis}[ declare function={ C=4; square(\t)=(\t)^2 + C; }, ] \addplot+ [samples=2] {C*x}; \addplot {square(x)}; \end{axis} \end{tikzpicture}

The definitions as such have the form functionargument list = definition where the argument list contains a comma-separated-list of arguments like \t or \t,\a,\b. The definition is a math expression which makes use of these arguments.

Please refer to the PGF/TikZ manual for more details.

\pgfplotstableread{file}

Please refer to the manual of PgfplotsTable, pgfplotstable.pdf, which is part of the pgfplots bundle.

\pgfplotstabletypeset{\macro}

Please refer to the manual of PgfplotsTable, pgfplotstable.pdf, which is part of the pgfplots bundle.

\pgfplotsiffileexists{filename}{true code}{false code} ¶

Invokes true code if filename exists and false code if not. Can be used in looping macros, for example to plot every data file until there are no more of them.

\pgfplotsutilifstringequal{first}{second}{true code}{false code} ¶

A simple “strcmp” tool which invokes true code if first \(=\)second and false code otherwise. This does not expand macros.

\pgfkeys ¶

\pgfeov ¶

\pgfkeysvalueof ¶

\pgfkeysgetvalue ¶

These commands are part of the TikZ way of specifying options, its sub-package pgfkeys. The \pgfplotsset command is actually nothing but a wrapper around \pgfkeys.

A short introduction into \pgfkeys can be found in [9] whereas the complete reference is, of course, the PGF/TikZ manual.

The key \pgfkeysvalueof{key name} expands to the value of a key; \pgfkeysgetvalue{key name}{\macro} stores the value of key name into \macro. The \pgfeov macro is used to delimit arguments for code keys in \pgfkeys, please refer to the references mentioned above.