Manual for Package pgfplots
2D/3D Plots in LATeX, Version 1.18.1
http://sourceforge.net/projects/pgfplots
The Reference
4.4About Options: Preliminaries
pgfplots knows a whole lot of key–value options which can be (re)defined to activate desired features or modified to apply some fine-tuning.
A key usually has a value (like a number, a string, or perhaps some
macro code). You can assign values to keys (“set keys”)
in many places in a
LaTeX
document. The value will remain effective until it is changed or
until the current
TeX
scope ends (which happens after a closing curly brace
‘}’, after \end{
name
} or, for example, after
\addplot).
Most keys can be used like
\begin{tikzpicture}
\begin{axis}[key=value,key2=value2] % axis-wide keys
...
\end{axis}
\end{tikzpicture}
which changes them for the complete axis. A key in this context can be any option defined in this manual, no matter if it has the /pgfplots/ or the /tikz/ key prefix. Note that key prefixes can be omitted in almost all cases.
A value can usually be provided without curly braces. For example,
if the manual contains something like ‘xmin={\(x\)-coordinate}’, you can safely skip the curly braces. The curly braces
are mandatory if values contain something which would otherwise
confuse the key setup (for example an equal sign
‘=’ or a comma ‘,’).
Some keys can be changed individually for each plot:
\begin{tikzpicture}
\begin{axis}
% keys
valid for single plots:
\addplot ... ; %
uses the "cycle list" to determine keys
\addplot [key=value,key2=value2] ... ; %
uses the provided keys (not the "cycle list")
\addplot+ [key=value,key2=value2] ... ; % appends
something to the "cycle list"
\end{axis}
\end{tikzpicture}
Besides these two possibilities, it is also possible to work with document-wide keys:
\chapter{My Chapter}
\pgfplotsset{
key=value,
key2=value2,
}
This chapter has a common key configuration:
\begin{tikzpicture}
\begin{axis}% uses the key config from above
...
\end{axis}
\end{tikzpicture}
In the example above, the \pgfplotsset command changes keys. The changes are permanent and will be used until
-
• you redefine them or
-
• the current environment (like \end{figure}) is ended or
-
• TeX encounters a closing brace ‘}’.
This includes document-wide preamble configurations like
\documentclass{article}
\usepackage{pgfplots}
\pgfplotsset{
xticklabel={$\mathsf{\pgfmathprintnumber{\tick}}$},
every axis/.append style={
font=\sffamily,
},
}
...
The basic engine to manage key–value pairs is pgfkeys which is part of pgf. This engine always has a key name and a key “path”, which is somehow similar to file name and directory of files. The common “directory” (key path) of pgfplots is ‘/pgfplots/’. Although the key definitions below provide this full path, it is always (well, almost always) safe to skip this prefix – pgfplots uses it automatically. The same holds for the prefixes ‘/tikz/’ which are common for all TikZ drawing options and ‘/pgf/’ which are for the (more or less) low-level commands of pgf. All these prefixes can be omitted.
One important concept is the concept of styles. A style is a key which contains one or more other keys. It can be redefined or modified until it is actually used by the internal routines. Each single component of TikZ and pgfplots can be configured with styles.
For example,
\pgfplotsset{legend style={line width=1pt}}
sets the line width for every legend to 1pt by appending ‘line width=1pt’ to the existing style for legends.
There are keys like
legend style,
ticklabel style, and
label style
which allow to modify the predefined styles (in this case the styles
for legends, ticklabels and axis labels, respectively). They are, in
general, equivalent to a
style name/.append style={}
command (the only difference is that the
/.append style
thing is a little bit longer). There is also the possibility to
define a new style (or to overwrite an already existing one) using
/.style={}.
There are several other styles predefined to modify the appearance, see Section 4.18.
-
\pgfplotsset{
key-value-list}
¶
Defines or sets all
options in
key-value-list. The
key-value-list
can contain any of the options in this manual which have the
prefix /pgfplots/ (however, you do not need to type
that prefix).
Inside of
key-value-list, the prefixes ‘/pgfplots/’ which are
commonly presented in this manual can be omitted (they are
checked automatically).
This command can be used to define default options for the complete document or a part of the document. For example,
\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)$,
}
can be used to set document-wise styles for line specifications, the legends’ style and axis labels. The settings remain in effect until the end of the current environment (like \end{figure}) or until you redefine them or until the next closing curly brace ‘}’ (whatever comes first).
You can also define new styles (collections of key–value pairs) with /.style and /.append style.
\pgfplotsset{
My Style 1/.style={xlabel=$x$, legend entries={1,2,3} },
My Style 2/.style={xlabel=$X$, legend entries={4,5,6} }
}
The /.style and /.append style key handlers are described in Section 4.18 in more detail.
-
Key handler
key/.code={TeX
code}
¶
Occasionally, the
pgfplots user interface offers to
replace parts of its routines. This is accomplished using so
called “code keys”. What it means is to replace the
original key and its behavior with new
TeX
code. Inside of
TeX
code, any command can be used. Furthermore, the
#1 pattern will be the argument provided to the key.
I’ve been invoked with ‘this here’
The example defines a (new) key named My Code. Essentially, it is nothing else but a \newcommand, plugged into the key–value interface. The second statement “invokes” the code key.
-
Key handler
key/.cd
¶
Each key has a fully qualified name with a (long) prefix, like /pgfplots/xmin. However, if the “current directory” is /pgfplots, it suffices to write just xmin. The /.cd key handler changes the “current directory” in this way.
The prefixes /tikz/ and /pgfplots/ are
checked automatically for any argument provided to
\begin{axis}[options] or
\addplot. So, you won’t need to worry about them, just omit them
– and look closer in case the package doesn’t
identify the option.
4.4.1PGFPlots and TikZ Options¶
This section is more or less technical and can be skipped unless one really wants to know more about this topic.
TikZ options and pgfplots options can be mixed inside of the axis arguments and in any of the associated styles. For example,
assigns the ‘legend columns’ option (a pgfplots option) and uses ‘font’ for drawing the legend (a TikZ option). The point is: legend columns needs to be known before the legend is typeset whereas font needs to be active when the legend is typeset. pgfplots sorts out any key dependencies automatically:
The axis environments will process any known pgfplots options, and all ‘every’ styles will be parsed for pgfplots options. Every unknown option is assumed to be a TikZ option and will be forwarded to the associated TikZ drawing commands. For example, the ‘font=\Large’ above will be used as argument to the legend matrix, and the ‘font=\Large’ argument in
will be used in the nodes for axis labels (but not the axis title, for example).
It is an error if you assign incompatible options to axis labels, for example ‘xmin’ and ‘xmax’ can’t be set inside of ‘every axis label’.