1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
\subsection{About 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|\marg{name} or, for example, after |\addplot|).
\noindent Most keys can be used like
\begin{codeexample}[code only]
\begin{tikzpicture}
\begin{axis}[key=value,key2=value2] % axis-wide keys
...
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent 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 somethig like `|xmin=|\marg{$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{codeexample}[code only]
\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}
\end{codeexample}
Besides these two possibilities, it is also possible to work with document-wide keys:
\begin{codeexample}[code only]
\section{My Section}
\pgfplotsset{
key=value,
key2=value2,
}
This section has a common key configuration:
\begin{tikzpicture}
\begin{axis}% uses the key config from above
...
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent In the example above, the |\pgfplotsset| command changes keys. The changes are permanent and will be used until
\begin{itemize}
\item you redefine them or
\item the current environment (like |\end{figure}|) is ended or
\item \TeX\ encounters a closing brace `|}|'.
\end{itemize}
This includes document--wide preamble configurations like
\begin{codeexample}[code only]
\documentclass{article}
\usepackage{pgfplots}
\pgfplotsset{
xticklabel={$\mathsf{\pgfmathprintnumber{\tick}}$},
every axis/.append style={
font=\sffamily,
},
}
...
\end{codeexample}
The basic engine to manage key--value pairs is |pgfkeys| which is part of \pgfname. 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 \pgfname. All these prefixes can be omitted.
One important concept is the concept of \emph{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,
\begin{codeexample}[code only]
\pgfplotsset{legend style={line width=1pt}}
\end{codeexample}
\noindent
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 \meta{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~\ref{sec:styles}.
\begin{command}{\pgfplotsset\marg{key-value-list}}
Defines or sets all options in \meta{key-value-list}. The \meta{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 \meta{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,
\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 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|.
\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}
\begin{handler}{{.code}=\marg{\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 \meta{\TeX\ code}. Inside of \meta{\TeX\ code}, any command can be used. Furthermore, the |#1| pattern will be the argument provided to the key.
\begin{codeexample}[]
\pgfplotsset{
My Code/.code={I've been invoked with `#1'}}
\pgfplotsset{My Code={this here}}
\end{codeexample}
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.
\end{handler}
\begin{handler}{{.code 2 args}=\marg{\TeX\ code}}
As |/.code|, but this handler defines a key which accepts two arguments. When the so defined key is used, the two arguments are available as |#1| and |#2|.
\end{handler}
\begin{handler}{{.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}|\oarg{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.
\end{handler}
\subsubsection{\textsc{Pgfplots} 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,
\begin{codeexample}[code only]
\pgfplotsset{every axis legend/.append style={
legend columns=3,font=\Large}}
\end{codeexample}
\noindent
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 \emph{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
\begin{codeexample}[code only]
\pgfplotsset{every axis label/.append style={
ylabel=Error,xlabel=Dof,font=\Large}}
\end{codeexample}
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|'.
|
