summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex513
1 files changed, 494 insertions, 19 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
index e5ba9fe8f32..af59f8e7109 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.tex
@@ -556,7 +556,126 @@ Please refer to \cite[section~18.6]{tikz} for more details about |plot function|
Disables the use of |samples| and |domain|.
\end{key}
+\subsubsection{Using External Graphics as Plot Sources}
+\begin{addplotoperation}[]{graphics}{\marg{file name}}
+ This plot type allows to extend the plotting capabilities of \PGFPlots\ beyond its own limitations. The idea is to generate the graphics as such (for example, a contour plot, a shaded surface or a large point cluster) with an external program like Matlab (tm) or |gnuplot|. The graphics, however, should \emph{not} contain an axis or descriptions. Then, we use |\includegraphics| and an \PGFPlots\ axis which fits exactly on top of the imported graphics.
+
+ Of course, one could do this manually by providing proper scales and such. The operation |plot graphics| is intended so simplify this process. However the \emph{main difficulty} is to get images with correct bounding box. Typically, you will have to adjust bounding boxes manually.
+
+ Let's start with an example: Suppose we use, for example, matlab to generate a surface plot like
+\begin{codeexample}[code only]
+[X,Y] = meshgrid( linspace(-3,3,500) );
+surf( X,Y, exp(-(X - Y).^2 - X.^2 ) );
+shading flat; view(0,90); axis off;
+print -dpng external1
+\end{codeexample}
+ \noindent which is then found in |external1.png|. The |surf| command of Matlab generates the surface, the following commands disable the axis descriptions, initialise the desired view and export it. Viewing the image in any image tool, we see a lot of white space around the surface -- Matlab has a particular weakness in producing tight bounding boxes, as far as I know. Well, no problem: use your favorite image editor and crop the image (most image editors can do this automatically). We could use the free ImageMagick command
+
+ |convert -trim external1.png external1.png|
+
+ to get a tight bounding box. Then, we use
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[enlargelimits=false,axis on top]
+ \addplot graphics
+ [xmin=-3,xmax=3,ymin=-3,ymax=3]
+ {external1};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent to load the graphics\footnote{Please note that I don't have a Matlab license, so I used \texttt{gnuplot} to produce an equivalent replacement graphics.} just as if we would have drawn it with \PGFPlots. The |axis on top| simply tells \PGFPlots\ to draw the axis on top of any plots (see its description).
+
+Our first test was successful -- and not difficult at all because graphics programs can automatically compute the bounding box. There are a couple of free tools available which can compute tight bounding boxes for |.eps| or |.pdf| graphics:
+\begin{enumerate}
+ \item The free vector graphics program |inkscape| can help here. Its feature ``File $\gg$ Document Properties: Fit page to selection'' computes a tight bounding box around every picture element.
+
+ However, some images may contain a rectanglar path which is as large as the bounding box (Matlab (tm) computes such |.eps| images). In this case, use the ``Ungroup'' method as often as necessary and remove such a path.
+
+ Finally, save as |.eps|.
+
+ However, |inkscape| appears to have problems with postscript fonts -- it substitutes them. This doesn't pose problems in this application because fonts shouldn't be part of such images -- the descriptions will be drawn by \PGFPlots.
+
+ \item The tool |pdfcrop| removes surrounding whitespace in |.pdf| images and produces quite good bounding boxes.
+\end{enumerate}
+
+\paragraph{Adjusting bounding boxes manually}
+In case you don't have tools at hand to provide correct bounding boxes, you can still use \TeX\ to set the bounding box manually. Some viewers like |gv| provide access to low--level image coordinates. The idea is to determine the number of units which need to be removed and communicate these units to |\includegraphics|.
+
+Let's follow this approach in a further example.
+
+ We use |gnuplot| to draw a (relatively stupid) example data set. The gnuplot script
+\begin{codeexample}[code only]
+set samples 30000
+set parametric
+unset border
+unset xtics
+unset ytics
+set output "external2.eps"
+set terminal postscript eps color
+plot [t=0:1] rand(0),rand(0) with dots notitle lw 5
+\end{codeexample}
+\noindent generates |external2.eps| with a uniform random sample of size $30000$. As before, we import this scatter plot into \PGFPlots\ using |plot graphics|. Again, the bounding box is too large, so we need to adjust it (|gnuplot| can do this automatically, but we do it anyway to explain the mechanisms):
+
+Using |gv|, I determined that the bounding box needs to be shifted |12| units to the left and |9| down. Furthermore, the right end is |12| units too far off and the top area has about |8| units space wasted. This can be provided to the |trim| option of |\includegraphics|, and we use |clip| to clip the rest away:
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[axis on top,title=Graphics Import]
+ \addplot graphics
+ [xmin=0,xmax=1,ymin=0,ymax=1,
+ % trim=left bottom right top
+ includegraphics={trim=12 9 12 8,clip}]
+ {external2};
+ \addplot coordinates {(0,0) (1,1)};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ So, |plot graphics| takes a graphics file along with options which can be passed to |\includegraphics|. Furthermore, it provides the information how to embed the graphics into an axis. The axis can contain any other |\addplot| command as well and will be resized properly.
+
+
+\paragraph{Details about \texttt{plot graphics}:}
+ The loaded graphics file is drawn with
+
+ |\node[/pgfplots/plot graphics/node] {\includegraphics[|\meta{options}|]|\marg{file name}|};|
+
+ where the |node| style is a configurable style. The node is placed at the coordinate designated by |xmin|, |ymin|.
+
+ The \meta{options} are any arguments provided to the |includegraphics| key (see below) and |width| and |height| determined such that the graphics fits exactly into the rectangle denoted by the |xmin|, |ymin| and |xmax|, |ymax| coordinates.
+
+ The scaling will thus ignore the aspect ratio of the external image and prefer the one used by \PGFPlots. You will need to provide |width| and |height| to the \PGFPlots\ axis to change its scaling. Use the |scale only axis| key in such a case.
+\end{addplotoperation}
+\begin{pgfplotsxykeylist}{
+ plot graphics/\x min=\marg{coordinate},
+ plot graphics/\x max=\marg{coordinate}}
+ These keys are required for |plot graphics| and provide information about the external data range. The graphics will be squeezed between these coordinates.
+\end{pgfplotsxykeylist}
+\begin{pgfplotskey}{plot graphics/includegraphics=\marg{options}}
+ A list of options which will be passed as--is to |\includegraphics|. Interesting options include the |trim=|\meta{left} \meta{bottom} \meta{right} \meta{top} key which reduces the bounding box and |clip| which discards everything outside of the bounding box. The scaling options won't have any effect, they will be overwritten by \PGFPlots.
+\end{pgfplotskey}
+\begin{stylekey}{/pgfplots/plot graphics/node}
+ A predefined style used for the node containing the graphics. The predefined value is
+\begin{codeexample}[code only]
+\pgfplotsset{
+ plot graphics/node/.style={
+ transform shape,
+ inner sep=0pt,
+ outer sep=0pt,
+ every node/.style={},
+ anchor=south west,
+ at={(0pt,0pt)},
+ rectangle
+ }
+}
+\end{codeexample}
+\end{stylekey}
+\begin{pgfplotskey}{plot graphics}
+ This key belongs to the public low--level plotting interface. You won't need it in most cases.
+
+ This key is similar to |sharp plot| or |smooth| or |const plot|: it installs a low--level plot--handler which expects exactly two points: the lower left corner and the upper right one. The graphics will be drawn between them. The graphics file name is expected as value of the |/pgfplots/plot graphics/src| key. The other keys described above need to be set correctly (excluding the limits, these are ignored at this level of abstraction). This key can be used independent of an axis.
+\end{pgfplotskey}
+
\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).
@@ -1191,7 +1310,7 @@ Here |ybar| yields |/pgfplots/ybar| because it is an argument to the axis, not t
/pgf/number format/1000 sep=},
ylabel=Population,
enlargelimits=0.05,
- legend style={at={(0.5,-0.1)},
+ legend style={at={(0.5,-0.15)},
anchor=north,legend columns=-1},
ybar interval=0.7,
]
@@ -1517,8 +1636,23 @@ Area plots may need modified legends, for example using the |area legend| key. F
\end{codeexample}
\subsubsection{Scatter Plots}
+The most simple scatter plots produce the same as the line plots above -- but they contain only markers. They are enabled using the |only marks| key of \Tikz.
+\begin{plottype}{only marks}
+Draws a simple scatter plot: all markers have the same appearance.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[enlargelimits=false]
+ \addplot+[only marks]
+ expression[samples=400]
+ {rand};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The |only marks| visualization style simply draws marks at every coordinate. Marks can be set with |mark=|\meta{mark name} and marker options like size and color can be specified using the |mark options=|\marg{style options} key (or by modifying the |every mark| style). The available markers along with the accepted style options can be found in section~\ref{sec:markers} on page~\pageref{sec:markers}.
+\end{plottype}
+
\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)$.
+More sophisticated scatter plots change the marker appearance for each data point. An example is that marker colors depend on the magnitude of function values $f(x)$ or other provided coordinates. The term ``scatter plot'' will be used for this type of plots in the following sections.
Scatter plots require ``source'' coordinates. These source coordinates can be the $y$ coordinate, or explicitly provided additional values.
@@ -1554,7 +1688,53 @@ Scatter plots can be configured using a set of options. One of them is mandatory
\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.
+ Usually, |scatter src| provides input data (numeric or string type) which is used to determine colors and other style options for markers.
+ The default configuration expects numerical data which is mapped linearly into the current color map.
+
+ 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 or below for some small examples). 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.
+
+ Here are examples for how to provide data for the choices |explicit| and |explicit symbolic|.
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+ \begin{axis}
+ % provide color data explicitly using [<data>]
+ % behind coordinates:
+ \addplot+[scatter]
+ [scatter src=explicit]
+ coordinates {
+ (0,0) [1.0e10]
+ (1,2) [1.1e10]
+ (2,3) [1.2e10]
+ (3,4) [1.3e10]
+ % ...
+ };
+
+ % Assumes a datafile.dat like
+ % xcolname ycolname colordata
+ % 0 0 0.001
+ % 1 2 0.3
+ % 2 2.1 0.4
+ % 3 3 0.5
+ % ...
+ % the file may have more columns.
+ \addplot+[scatter]
+ [scatter src=explicit]
+ table[x=xcolname,y=ycolname,meta=colordata]
+ {datafile.dat};
+
+ % Assumes a datafile.dat like
+ % 0 0 0.001
+ % 1 2 0.3
+ % 2 2.1 0.4
+ % 3 3 0.5
+ % ...
+ % the first three columns will be used here:
+ \addplot+[scatter]
+ [scatter src=explicit]
+ file {datafile.dat};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
Please note that |scatter src|$\neq$|none| results in computational work even if |scatter=false|.
\end{pgfplotskey}
@@ -1611,22 +1791,24 @@ Scatter plots can be configured using a set of options. One of them is mandatory
\begin{axis}[scatter/classes={
a={mark=square*,blue},%
b={mark=triangle*,red},%
- c={mark=o,draw=black,fill=black}}]
+ c={mark=o,draw=black}}]
- \addplot+[scatter,only marks]
+ % \addplot[] is better than \addplot+[] here:
+ % it avoids scalings of the cycle list
+ \addplot[scatter,only marks]
plot[scatter src=explicit symbolic]
coordinates {
- (0.1,0.15) [a]
+ (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.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.76,0.5) [b]
(0.55,0.32) [c]
};
\end{axis}
@@ -1634,6 +1816,34 @@ Scatter plots can be configured using a set of options. One of them is mandatory
\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.
+\begin{codeexample}[code only]
+\begin{tikzpicture}
+\begin{axis}[scatter/classes={
+ 0={mark=square*,blue},%
+ 1={mark=triangle*,red},%
+ 2={mark=o,draw=black,fill=black}}]
+
+ % Assumes datafile.dat looks like
+ % x y label
+ % 5.000000e-01 7.500000e-01 1
+ % 1.000000e+00 6.718750e-01 2
+ % 1.000000e+00 5.597630e-01 2
+ % 5.000000e-01 1.250000e-01 2
+ % 1.000000e+00 6.603350e-01 0
+ % 5.000000e-01 0.000000e+00 0
+ % 0.000000e+00 5.000000e-01 0
+ % 1.000000e+00 0.000000e+00 2
+ % 5.000000e-01 1.250000e-01 1
+ % 1.000000e+00 6.213180e-01 1
+ % ...
+ \addplot[scatter,only marks]
+ table[scatter src=explicit symbolic,x index=x,y index=y,meta=label]
+ {datafile.dat}
+ ;
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
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.
@@ -1782,6 +1992,9 @@ And with |\usetikzlibrary{plotmarks}|:
\item[mark=diamond*] \showit{mark=diamond*}
\item[mark=pentagon] \showit{mark=pentagon}
\item[mark=pentagon*] \showit{mark=pentagon*}
+ \item[mark=text] \showit{mark=text,every mark/.append style={scale=0.5}}
+
+ This marker is special as it can be configured freely. The character (or even text) used is configured by a set of variables, see below.
\end{longdescription}
All these options have been drawn with the additional options
\begin{codeexample}[code only]
@@ -1793,6 +2006,29 @@ All these options have been drawn with the additional options
}
]
\end{codeexample}
+Please see section~\ref{sec:colors} for how to change draw- and fill colors.
+
+\begin{key}{/pgf/text mark=\marg{text} (initially p)}
+ Changes the text shown by |mark=text|.
+
+ With |/pgf/text mark=m|: \pgfkeys{/pgf/text mark=m}\showit{mark=text,every mark/.append style={scale=0.5}}
+
+ With |/pgf/text mark=A|: \pgfkeys{/pgf/text mark=A}\showit{mark=text,every mark/.append style={scale=0.5}}
+
+ There is no limitation about the number of characters or whatever. In fact, any \TeX\ material can be inserted as \marg{text}, including images.
+\end{key}
+\begin{key}{/pgf/text mark/style=\marg{options for \texttt{mark=text}}}
+ Defines a set of options which control the appearance of |mark=text|.
+
+ If |/pgf/text mark/as node=false| (the default), \marg{options} is provided as argument to |\pgftext| -- which provides only some basic keys like |left|, |right|, |top|, |bottom|, |base| and |rotate|.
+
+ If |/pgf/text mark/as node=true|, \marg{options} is provided as argument to |\node|. This means you can provide a very powerful set of options including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc.
+\end{key}
+\begin{key}{/pgf/text mark/as node=\mchoice{true,false} (initially false)}
+ Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|.
+
+ The first choice is highly flexible and possibly slow, the second is very fast and usually enough.
+\end{key}
\begin{key}{/tikz/mark size=\marg{dimension}}
This \Tikz\ option allows to set marker sizes to \marg{dimension}. For circular markers, \marg{dimension} is the radius, for other plot marks it is about half the width and height.
@@ -1895,11 +2131,23 @@ The following line styles are predefined in \Tikz.
Besides linestyles, \PGF\ also offers (a lot of) arrow heads. Please refer to~\cite{tikz} for details.
\endgroup
+
\subsubsection{Font Size and Line Width}
Often, one wants to change line width and font sizes for plots. This can be done using the following options of \Tikz.
\begin{key}{/tikz/font=\marg{font name} (initially \textbackslash normalfont)}
Sets the font which is to be used for text in nodes (like tick labels, legends or descriptions).
+
+ A font can be any \LaTeX\ argument like |\footnotesize| or |\small\bfseries|\footnote{Con\TeX t and plain \TeX\ users need to provide other statements, of course.}.
+
+ It may be useful to change fonts only for specific axis descriptions, for example using
+\begin{codeexample}[code only]
+\pgfplotsset{
+ tick label style={font=\small},
+ label style={font=\small},
+ legend style={font=\footnotesize}
+}
+\end{codeexample}
\end{key}
\begin{key}{/tikz/line width=\marg{dimension} (initially 0.4pt)}
@@ -1970,6 +2218,7 @@ This example shows the same plots as on page~\pageref{page:plotcoords:src} (usin
\end{codeexample}
\subsubsection{Colors}
+\label{sec:colors}
{%
\def\showcolorandname#1{%
\showcolor{#1}~#1%
@@ -1977,7 +2226,7 @@ This example shows the same plots as on page~\pageref{page:plotcoords:src} (usin
\def\showcolor#1{%
\tikz \draw[black,fill={#1}] (0,0) rectangle (1em,0.6em);%
}%
-\PGF\ uses the color support of |xcolor|. Therefore, the main reference for how to specify colors is the |xcolor| manual~\cite{xcolor}. The \PGF\ manual~\cite{tikz} is the reference for how to select colors for specific purposes like drawing, filling, shading, patterns etc. This section contains a short overview over the specification of colors in~\cite{xcolor} (which is not limited to \PGFPlots).
+\PGF\ uses the color support of |xcolor|. Therefore, the main reference for how to specify colors is the |xcolor| manual~\cite{xcolor}. The \PGF\ manual~\cite{tikz} is the reference for how to select colors for specific purposes like drawing, filling, shading, patterns etc.\ This section contains a short overview over the specification of colors in~\cite{xcolor} (which is not limited to \PGFPlots).
The package |xcolor| defines a set of predefined colors, namely
\showcolorandname{red},
@@ -2035,15 +2284,39 @@ 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.
}%
+\begin{keylist}{
+ /tikz/color=\marg{a color},
+ /tikz/draw=\marg{stroke color},
+ /tikz/fill=\marg{fill color}}
+ These keys are (generally) used to set colors. Use |color| to set the color for both, drawing and filling. Instead of |color=|\marg{color name} you can simply write \marg{color name}. The |draw| and |fill| keys only set colors for stroking and filling, respectively.
+
+ Use |draw=none| to disable drawing and |fill=none| to disable filling\footnote{Up to now, plot marks always have a stroke color (some also have a fill color). This restriction may be lifted in upcoming versions.}.% This does also work for markers.
+%--------------------------------------------------
+% \begin{codeexample}[]
+% \begin{tikzpicture}
+% \begin{axis}
+% \addplot+[only marks,mark=square*,
+% mark options={fill=red!50!white,draw=none}]
+% {4*x^2 - 2*x +4 };
+% \end{axis}
+% \end{tikzpicture}
+% \end{codeexample}
+%--------------------------------------------------
+
+ Since these keys belong to \Tikz, the complete documentation can be found in the \Tikz\ manual~\cite[Section ``Specifying a Color'']{tikz}.
+\end{keylist}
+
\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
+ Changes the current color map to the already defined map named \marg{color map name}. The predefined color map is
\begin{tabular}{>{\ttfamily}ll}
hot & \pgfplotsshowcolormap{hot}\\
\end{tabular}
+ Further colormaps are described below.
+
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).
@@ -2054,17 +2327,110 @@ It is also possible to use RGB values, the HSV color model or the HTML color syn
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)
+rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); 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)}
+\pgfplotsshowcolormapexample{rgb(0cm)=(1,0,0); rgb(1cm)=(0,1,0); rgb255(2cm)=(0,0,255); 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.
+\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. The |rgb255| also expects three RGB components, but in the range $[0,255]$. Finally, |gray| specifies a color in parenthesis with the same value for each, R G and B and |color| accesses predefined colors.
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[
+ colormap={bw}{gray(0cm)=(0); gray(1cm)=(1)}]
+ \addplot+[scatter,only marks]
+ plot[scatter src=y,domain=0:8,samples=100]
+ {exp(x)};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
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|.
+Available colormaps are shows below.
+
\paragraph{Remark:} Currently, only equidistant \marg{color specification}s are supported (each interval must have the same length).
\end{pgfplotskey}
+\begin{stylekey}{/pgfplots/colormap/hot}
+ A style which installs the colormap
+
+ |{color(0cm)=(blue); color(1cm)=(yellow); color(2cm)=(orange); color(3cm)=(red)}|
+
+ \pgfplotsshowcolormap{hot}
+
+ This is the preconfigured colormap.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/bluered}
+ A style which installs the colormap
+
+ |{rgb255(0cm)=(0,0,180); rgb255(1cm)=(0,255,255); rgb255(2cm)=(100,255,0); |
+
+ |rgb255(3cm)=(255,255,0); rgb255(4cm)=(255,0,0); rgb255(5cm)=(128,0,0)}|,
+
+ \pgfplotsshowcolormap{bluered}
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[colormap/bluered]
+ \addplot+[scatter]
+ expression[scatter src=x,samples=50]
+ {sin(deg(x))};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ \paragraph{Remark:}
+ The style |bluered| (re-)defines the colormap and activates it. \TeX\ will be slightly faster if you call |\pgfplotsset{colormap/bluered}| in the preamble (to create the colormap once) and use |colormap name=bluered| whenever you need it. This remark holds for every colormap style which follows. But you can simply ignore this remark.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/cool}
+ A style which installs the colormap
+
+ |{rgb255(0cm)=(255,255,255); rgb255(1cm)=(0,128,255); rgb255(2cm)=(255,0,255)}|
+
+ \pgfplotsshowcolormap{cool}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/greenyellow}
+ A style which installs the colormap
+
+ |{rgb255(0cm)=(0,128,0); rgb255(1cm)=(255,255,0)}|
+
+ \pgfplotsshowcolormap{greenyellow}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/redyellow}
+ A style which installs the colormap
+
+ |{rgb255(0cm)=(255,0,0); rgb255(1cm)=(255,255,0)}|
+
+ \pgfplotsshowcolormap{redyellow}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/colormap/blackwhite}
+ A style which installs the colormap
+
+ |{gray(0cm)=(0); gray(1cm)=(1)}|
+
+ \pgfplotsshowcolormap{blackwhite}
+\end{stylekey}
+
+\begin{command}{\pgfplotscolormaptoshadingspec\marg{colormap name}\marg{right end size}\marg{\textbackslash macro}}
+ A command which converts a colormap into a \PGF\ shading's color specification. It can be used in commands like |\pgfdeclare*shading| (see the \PGF\ manual~\cite{tikz} for details).
+
+ The first argument is the name of a (defined) colormap, the second the rightmost dimension of the specification. The result will be stored in \meta{\textbackslash macro}.
+\begin{codeexample}[]
+ % convert `hot' -> \result
+ \pgfplotscolormaptoshadingspec{hot}{8cm}\result
+ % define and use a shading in pgf:
+ \def\tempb{\pgfdeclarehorizontalshading{tempshading}{1cm}}%
+ % where `\result' is inserted as last argument:
+ \expandafter\tempb\expandafter{\result}%
+ \pgfuseshading{tempshading}%
+\end{codeexample}
+The usage of the result \meta{\textbackslash macro} is a little bit low--level.
+\end{command}
+
\subsubsection{Options Controlling Linestyles}
\label{sec:cycle:list}%
@@ -2213,7 +2579,6 @@ These predefined cycle lists habe been created with
{dashed,mark=o},
{loosely dotted,mark=+},
{brown!60!black,mark options={fill=brown!40},mark=otimes*}}
-}
...
\begin{axis}[cycle list name=mylist]
...
@@ -2517,6 +2882,7 @@ The default is
}}
\end{codeexample}
+% \usetikzlibrary{patterns}
\begin{codeexample}[]
% \usetikzlibrary{patterns}
\begin{tikzpicture}
@@ -2805,6 +3171,7 @@ In some applications, more than one $y$ axis is used if the $x$ range is the sam
\end{enumerate}
You may want to consider different legend styles.
It is also possible to use only the axis, without any plots:
+% \usepackage{textcomp}
\begin{codeexample}[]
% \usepackage{textcomp}
\begin{tikzpicture}
@@ -2936,6 +3303,109 @@ Axis scaling and clipping will be done as if you did not use |hide x axis|.
A style which sets both, |hide x axis| and |hide y axis|.
\end{stylekey}
+\subsubsection{Adjusting Descriptions for Different Scales}
+It is reasonable to change font sizes, marker sizes etc. together with the overall plot size: Large plots should also have larger fonts and small plots should have small fonts and a smaller distance between ticks.
+
+\begin{keylist}{
+ /tikz/font=\mchoice{\textbackslash normalfont,\textbackslash small,\textbackslash tiny,$\dotsc$},
+ /pgfplots/max space between ticks=\marg{integer},
+ /tikz/mark size=\marg{integer}}
+ These keys should be adjusted to the figure's dimensions. Use
+\begin{codeexample}[code only]
+\pgfplotset{tick label style={font=\footnotesize},
+ label style={font=\small},
+ legend style={font=\small}
+}
+\end{codeexample}
+ to provide different fonts for different descriptions.
+
+ The |max space between ticks| is described on page~\pageref{maxspacebetweenticks} and configures the approximate distance between successive tick labels (in |pt|). Please omit the |pt| suffix here.
+\end{keylist}
+
+There are a couple of predefined scaling styles which set some of these options:
+
+\begin{stylekey}{/pgfplots/normalsize}
+ Re-initialises the standard scaling options of \PGFPlots.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[normalsize,
+ title=A ``normalsize'' figure,
+ xlabel=The $x$ axis,
+ ylabel=The $y$ axis,
+ legend entries={Leg}]
+ \addplot {max(4*x,7*x)};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ The initial setting is
+\begin{codeexample}[code only]
+/pgfplots/normalsize/.style={
+ /pgfplots/width=240pt,
+ /pgfplots/height=207pt,
+ /pgfplots/max space between ticks=35
+}
+\end{codeexample}
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/small}
+ Redefines several keys such that the axis is ``smaller''.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[small,
+ title=A ``small'' figure,
+ xlabel=The $x$ axis,
+ ylabel=The $y$ axis,
+ legend entries={Leg}]
+ \addplot {x^2};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The initial setting is
+\begin{codeexample}[code only]
+/pgfplots/small/.style={
+ /pgfplots/width=6.5cm,
+ /pgfplots/height=,
+ /pgfplots/max space between ticks=25
+}
+\end{codeexample}
+Feel free to redefine the scaling -- the option may still be useful to get more ticks without typing too much. You could, for example, set |small,width=6cm|.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/footnotesize}
+ Redefines several keys such that the axis is even smaller. The tick labels will have |\footnotesize|.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[footnotesize,
+ title=A ``footnotesize'' figure,
+ xlabel=The $x$ axis,
+ ylabel=The $y$ axis,
+ legend entries={Leg}]
+ \addplot+[const plot]
+ coordinates {
+ (0,0) (1,1) (3,3) (5,10)
+ };
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The initial setting is
+\begin{codeexample}[code only]
+/pgfplots/footnotesize/.style={
+ /pgfplots/width=5cm,
+ /pgfplots/height=,
+ legend style={font=\footnotesize},
+ tick label style={font=\footnotesize},
+ label style={font=\small},
+ /pgfplots/max space between ticks=20,
+ every mark/.append style={mark size=8},
+ ylabel style={yshift=-0.3cm}
+},
+\end{codeexample}
+As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards.
+\end{stylekey}
\subsection{Scaling Options}
@@ -3481,7 +3951,7 @@ Allows to choose between linear (=normal) or logarithmic axis scaling or logplot
This option has nothing to do with path clipping, it only affects how the axis limits are computed.
\end{pgfplotskey}
-\begin{pgfplotsxykey}{enlarge \x\ limits=\mchoice{true,false,auto,\marg{val}} (default true)}
+\begin{pgfplotsxykey}{enlarge \x\ limits=\mchoice{true,false,auto,\marg{val}} (initially auto)}
Enlarges the axis size for one axis somewhat if enabled.
You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of your data and |enlarge x limits| will enlarge the canvas such that the axis doesn't touch the plots.
@@ -3548,6 +4018,7 @@ The default choice for tick \emph{positions} in normal plots is to place a tick
The default tick positions can be reconfigured with
\begin{itemize}
+\label{maxspacebetweenticks}
\item `|max space between ticks=|\marg{number}' where the integer argument denotes the maximum space between adjacent ticks in full points. The suffix ``|pt|'' has to be omitted and fractional numbers are not supported. The default is~\axisdefaulttickwidth.
\item `|try min ticks=|\marg{number}' configures a loose lower bound on the number of ticks. It should be considered as a suggestion, not a tight limit. The default is~\axisdefaulttryminticks. This number will increase the number of ticks if `|max space between ticks|' produces too few of them.
\item `|try min ticks log=|\marg{number}' The same for logarithmic axis.
@@ -4589,7 +5060,7 @@ The default value is |anchor=south west|. You can use anchors in conjunction wit
\label{sec:align}%
The default axis anchor is |south west|, which means that the picture coordinate $(0,0)$ is the lower left corner of the axis. As a consequence, the \Tikz\ option ``|baseline|'' allows vertical alignment of adjacent plots:
\begin{codeexample}[]
-\tikzset{domain=-1:1}
+\pgfplotsset{domain=-1:1}
\begin{tikzpicture}
\begin{axis}[xlabel=A normal sized $x$ label]
\addplot[smooth,blue,mark=*] {x^2};
@@ -4604,7 +5075,7 @@ The default axis anchor is |south west|, which means that the picture coordinate
\end{codeexample}
\begin{codeexample}[]
-\tikzset{domain=-1:1}
+\pgfplotsset{domain=-1:1}
\begin{tikzpicture}[baseline]
\begin{axis}[xlabel=A normal sized $x$ label]
\addplot[smooth,blue,mark=*] {x^2};
@@ -5039,6 +5510,10 @@ Allows to insert \marg{commands} right after the end of the clipped drawing comm
The initial choice |clip marker paths=false| causes markers to be drawn \emph{after} the clipped region. Only their positions will be clipped. As a consequence, markers will be drawn completely, or not at all. The value |clip marker paths=true| is here for backwards compatibility: it does not introduce special marker treatment, so markers may be drawn partially if they are close to the clipping boundary\footnote{Please note that clipped marker paths may be slightly faster during \TeX\ compilation.}.
\end{pgfplotskey}
+\begin{pgfplotskey}{clip=\mchoice{true,false} (initially true)}
+ Whether any paths inside an axis shall be clipped.
+\end{pgfplotskey}
+
\begin{pgfplotskey}{axis on top=\mchoice{true,false} (initially false)}
If set to |true|, axis lines, ticks, tick labels and grid lines will be drawn on top of plot graphics.
\begin{codeexample}[]