summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex398
1 files changed, 345 insertions, 53 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
index c5c8537a8d5..8b6f77d101f 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.scaling.tex
@@ -1,59 +1,94 @@
\subsection{Scaling Options}
+There are a various options which control or change the scaling of an axis. Here, ``scaling'' typically means two aspects: first, the unit vector size in each direction and second, the displayed limits in each direction. Both together control the size of the axis box. In addition, axis descriptions change the size. However, \PGFPlots\ scales only units and determines limits. It does not scale axis descriptions by default in order to keep consistent font sizes between the text and the figure.
-\begin{pgfplotskey}{width=\marg{dimen}}
-Sets the width of the final picture to \marg{dimen}. If no |height| is specified, scaling will respect aspect ratios.
+Often, one wishes to provide the target size only and let \PGFPlots\ do the rest. This is the default; it scales the axis to |width| and |height|. If you provide one of these options, the axis will be rescaled while keeping the aspect ratio.
-\paragraph{Remarks:}
-\begin{itemize}
- \item The scaling only affects the width of one unit in $x$-direction or the height for one unit in $y$-direction. Axis labels and tick labels won't be resized, but their size is used to determine the axis scaling.
+Occasionally, one wants to provide unit vectors explicitly to ensure that one unit takes a prescribed amount of space. This is possible by means of the |x|, |y|, and |z| keys. In such a case, the |width| and |height| options will be ignored (or only applied for the unspecified unit vectors).
- \item You can use the |scale=|\marg{number} option,
-\begin{codeexample}[code only]
-\begin{tikzpicture}[scale=2]
-\begin{axis}
-...
+Another common approach is to enforce specific |unit vector ratio|s: for example by specifying that each unit should take the same amount of space using |axis equal|. Here, \PGFPlots\ scales the lengths of all vectors uniformly, i.e.\ it applies the same scale to each vector. This is done by means of the |scale mode| configuration which is basically one of |scale mode=stretch to fill| or |scale mode=scale uniformly|: \PGFPlots\ tries to satisfy the prescribed |width| and |height| arguments by finding a \emph{common} scaling factor. In addition, it attempts to enlarge the limits individually to fit into the prescribed dimensions.
+
+In addition, you can use the option |/pgfplots/scale| to simply scale all final units up by some prescribed factor. This does not change text labels.
+
+If needed, you can also supply |/tikz/scale| to an axis. This will scale the complete resulting image, including all text labels.
+
+\subsubsection{Common Scaling Options}
+All common options mentioned in the previous paragraphs are described here.
+
+\begin{pgfplotskey}{width=\marg{dimen} (initially empty)}
+Sets the width of the final picture to \marg{dimen}.
+
+Any non-empty dimension like |width=5cm| sets the desired target width. Any \TeX\ unit is accepted (like |200pt| or |5in|).
+
+An empty value |width={}| means ``use default width or rescale proportionally to |height|''. In this case, \PGFPlots\ uses the value of |\axisdefaultwidth| as target quantity. However, if the |height| key has been set, \PGFPlots\ will rescale the |\axisdefaultwidth| in a way which keeps the ratio between |\axisdefaultwidth| and |\axisdefaultheight|. This allows to specify just one of |width| and |height| and keep aspect ratios.
+
+Consequently, if you specify just |width=5cm| but leave the default |height={}|, the scaling will respect the initial aspect ratio.
+
+The scaling affects the unit vectors for $x$, $y$, and $z$. It does not change the size of text labels or axis descriptions.
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[width=5cm]
+ \addplot {x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
- to scale the complete picture.
- \item The \Tikz-options |x| and |y| which set the unit dimensions in $x$ and $y$ directions can be specified as arguments to |\begin{axis}[x=1.5cm,y=2cm]| if needed (see below). These settings override the |width| and |height| options.
+Please note that \PGFPlots\ only estimates the size needed for axis- and tick labels. The estimate assumes a fixed amount of space for anything which is outside of the axis box. This has the effect that the final images may be slightly larger or slightly smaller than the prescribed dimensions. However, the fixed amount is always the same; it is set to~|45pt|. That means that multiple pictures with the same target dimensions will have the same size for their axis boxes -- even if the size for descriptions varies.
- \item You can also force a fixed width/height of the axis (without looking at labels) with
-\begin{codeexample}[code only]
+It is also possible to scale the \emph{axis box} to the prescribed width/height. In that case, the total width will be larger due to the axis descriptions. However, the axis box fills the desired dimensions exactly.
+\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[width=5cm,scale only axis]
- ...
+ \addplot {x};
\end{axis}
\end{tikzpicture}
\end{codeexample}
- \item Please note that up to the writing of this manual, \PGFPlots\ only estimates the size needed for axis- and tick labels. It does not include legends which have been placed outside of the axis\footnote{I.e. the `\texttt{width}' option will not work as expected, but the bounding box is still ok.}. This may be fixed in future versions.
+ \paragraph{Note:} changing |width| and/or |height| changes \emph{only} the unit vector sizes. In particular, it does not change the font size for any axis description, nor does it change the default spacing between adjacent tick labels. It is best-practice to use |width|/|height| for ``small'' changes, i.e.\ changes for which the font size should remain the same. Consider using one of the styles |normalsize|, |small|, |footnotesize|, or |tiny| which are described in Section~\ref{sec:scaling:styles} on page~\pageref{sec:scaling:styles}, and \emph{then} change to your desired dimensions if you need a different ``quality'' of scaling.
+
+ \begin{command}{\axisdefaultwidth}
+ This macro defines the default width. It is preset to |240pt|.
- Use the |x=|\marg{dimension}, |y=|\marg{dimension} and |scale only axis| options if the scaling happens to be wrong.
-\end{itemize}
+ This default width defines the aspect ratio which will be used whenever just one of |width| or |height| is specified: the aspect ratio is the ratio between |\axisdefaultwidth| and |\axisdefaultheight|.
+
+ You can change it using
+\begin{codeexample}[code only]
+\def\axisdefaultwidth{10cm}
+\end{codeexample}
+ \end{command}
\end{pgfplotskey}
-\begin{pgfplotskey}{height=\marg{dimen}}
- See |width|.
+\begin{pgfplotskey}{height=\marg{dimen} (initially empty)}
+ Works in the same way as |width| except that an empty value |height={}| defaults to ``use either |\axisdefaultheight| or scale proportionally if just |width| has been changed''.
+
+ \begin{command}{\axisdefaultheight}
+ This macro defines the default height. It is preset to |207pt|.
+
+ See |\axisdefaultwidth|.
+ \end{command}
\end{pgfplotskey}
\begin{pgfplotskey}{scale only axis=\mchoice{true,false} (initially false)}
-If |scale only axis| is enabled, label, tick and legend dimensions won't influence the size of the axis rectangle, that means |width| and |height| apply only to the axis rectangle.
+If |scale only axis| is enabled, |width| and |height| apply only to the axis rectangle. Consequently, the resulting figure is larger that |width| and |height| (because of any axis descriptions). However, the axis box has exactly the prescribed target dimensions.
If |scale only axis=false| (the default), \PGFPlots\ will try to produce the desired width \emph{including} labels, titles and ticks.
\end{pgfplotskey}
\begin{pgfplotsxykeylist}{
- \x=\marg{dimen},
+ \x=\marg{dimen} (initially empty),
\x={\{(\meta{x},\meta{y})\}}}
-Sets the unit vectors for $x$ (or $y$). Every logical plot coordinate $(x,y)$ is drawn at the position
+Allows to provide zero, one, two, or three of the target unit vectors.
+
+In this context, a ``unit vector'' is a two--dimensional vector which defines the projection onto the canvas:
+every logical plot coordinate $(x,y)$ is drawn at the canvas 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.
+For a standard three--dimensional axis, a plot coordinate $(x,y,z)$ is drawn at
+\[ x \cdot \begin{bmatrix} e_{xx} \\ e_{xy} \end{bmatrix} + y \cdot \begin{bmatrix} e_{yx} \\ e_{yy} \end{bmatrix} + z \cdot \begin{bmatrix} e_{zx} \\ e_{zy} \end{bmatrix}. \]
-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|. Note that you should not use negative values for \meta{dimen} (consider using |x dir| and its variants to reverse axis directions).
+The initial setting assigns empty values to each of these keys, i.e. |x={},y={},z={}|. In this case, \PGFPlots\ is free to choose these vectors as best. To this end, it uses |width|, |height|, |scale mode|, |plot box ratio|, |unit vector ratio|, |view|, and the axis limits.
+
+The key |x=|\marg{dimen} simply sets $e_x = (\meta{dimen},0)^T $ while |y=|\marg{dimen} sets $e_y = (0,\meta{dimen})^T$. Using |z=|\marg{dimen} results in $e_z = (\meta{dimen},\meta{dimen})^T$. In this context, \meta{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. Note that you should not use negative values for \meta{dimen} (consider using |x dir| and its variants to reverse axis directions).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[x=1cm,y=1cm]
@@ -70,7 +105,17 @@ Here, \marg{dimen} is any \TeX\ size like |1mm|, |2cm| or |5pt|. Note that you s
\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 similarly. This allows to define skewed or rotated axes.
+Note that if you change the unit vector for just one direction, the other vector(s) will be chosen by \PGFPlots\ -- and scaled in order to fill the prescribed |width| and |height| as best as \PGFPlots\ can (but see remarks for three--dimensional plots at the end of this key).
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[x=1cm,
+ title=Height is deduced from height option]
+\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 keys for |y| and |z| work in a similar way. This allows to define skewed or rotated axes.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -90,9 +135,8 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
\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$.
+ Setting |x| and/or |y| for logarithmic axis will set the dimension used for $1 \cdot e \approx 2.71828$ (or whatever has been set as |log basis x|).
Please note that it is \emph{not} possible to specify |x| as argument to |tikzpicture|. The option
\begin{codeexample}[code only]
@@ -102,13 +146,15 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
\end{axis}
\end{tikzpicture}
\end{codeexample}
- won't have any effect because an axis rescales its coordinates (see the |width| option).
+ does not have any effect because an axis rescales its coordinates (see the |width| option).
+ Note that providing unit vectors explicitly usually causes \PGFPlots\ to ignore any other scaling options. In other words: if you say |y=0.1cm|, \PGFPlots\ will use $(0\text{cm},0.1\text{cm})$ as $y$ projection vector. However, if you add |scale mode=scale uniformly|, you allow \PGFPlots\ to change the \emph{lengths} of your vectors. Of course, it will keep their relative directions and relative sizes. In this case, \PGFPlots\ will try to determine a good common scaling factor \emph{and} it will try to change the axis limits in order to fill the prescribed |width| and |height| (see the documentation for |scale mode| for details).
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
- x={(1cm,-0.5cm)},
- y=1cm,
+ title=Allow to rescale \emph{lengths},
+ x={(0.1cm,-0.05cm)},
+ y=0.1cm,
z=0cm,
axis on top,
scale mode=scale uniformly,
@@ -117,6 +163,9 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
\end{axis}
\end{tikzpicture}
\end{codeexample}
+ \noindent In the example above, \PGFPlots\ decided that it should only rescale units -- at the expensive of the |width| constraint.
+
+\paragraph{Changes to font sizes:} see also Section~\ref{sec:scaling:styles} if you want to change font sizes or the density of tick labels in a simple way.
\paragraph{Explicit units for 3D axes:} As of version~1.5, it is also possible to supply unit vectors to three-dimensional axes. In this case, the following extra assumptions need to be satisfied:
\begin{enumerate}
@@ -125,28 +174,15 @@ The second syntax, |x={(|\meta{x}|,|\meta{y}|)}| sets $e_x = (\meta{x},\meta{y})
Consider using |x dir=reverse| or its variants in case you want to reverse directions.
- \item For three-dimensional axes, \PGFPlots\ computes a view direction out of the provided unit vectors. The view direction is required to realize the |z buffer| feature (i.e.\ to decide about depths)\footnote{\PGFPlots\ provides a debug option called \texttt{view dir=\marg{x}\marg{y}\marg{z}} to override the view direction, should that ever be interesting.}.
+ \item For three-dimensional axes, \PGFPlots\ computes a view direction out of the provided unit vectors. The view direction is required to allow the |z buffer| feature (i.e.\ to decide about depths)\footnote{\PGFPlots\ provides a debug option called \texttt{view dir=\marg{x}\marg{y}\marg{z}} to override the view direction, should that ever be interesting.}.
\end{enumerate}
-This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, compare the examples in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d}.
+This feature is used to for the \verbpdfref{\addplot3 graphics} feature, compare the examples in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d}.
\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}{scale mode=\mchoice{auto,none,stretch to fill,scale uniformly} (initially auto)}
- Specifies how |width|, |height|, and the three unit vector keys |x|, |y|, and |z| are combined to produce the final image.
-
- The initial choice \declaretext{auto} chooses one of the other possible choices depending on the actual context. More precisely, it is the same as |none| if at least one of |x|, |y|, or |z| is provided (meaning that these keys are the final unit size). If no unit is provided, it defaults to |stretch to fill|.
-
- The choice |none| does not apply any rescaling at all. Use this if prescribed lengths of |x|, |y| (and perhaps |z|) should be used. In other words: it ignores |width| and |height|. In this case, you may want to set |x post scale| and its variants to rescale units manually.
-
- The choice |stretch to fill| takes |x|, |y|, and |z| as they have been found (either from user input or from some automatic processing) and rescales the axis with two \emph{separate} scales: one which results in the proper |width| and one which results in the proper |height|. As a consequence, the unit vectors are modified and distorted such that the final image fits into the prescribed dimensions. This is usually what one expects unless one provides unit directions explicitly.
-
- The choice |scale uniformly| is similar -- but it applies only \emph{one} scaling factor to fit into the prescribed dimensions. This scaling factor will be the same for both, |width| and |height|. Naturally, this will result in unsatisfactory results because either the final width or the final height will not be met. Therefore, this choice will enlarge or shrink limits to get the desired dimensions. Thus, the unit vectors have exactly the same size \emph{relations and angles} as they had before the scaling; only their magnitude is changed uniformly. But due to the given constraints, parts of the image may be empty or may no longer be visible. In case the outcome needs manual improvements, you can improve the visibility by modifying |width| and/or |height| (more freedom is not supported for this choice). Note that \PGFPlots\ implements this rescaling \textbf{if and only if} $e_{yx} = 0$ (for two--dimensional axes) or $e_{zx} = 0$ (for three-dimensional axes). In other words: for two--dimensional axes, the |y| vector has to be parallel to the canvas $y$ direction and for three-dimensional axes, the same holds for the |z| vector. The idea is to rescale only the vertical part of one unit vector and to change the limits of that respective axis simultaneously. The |scale uniformly| choice is used to realize the \verbpdfref{\addplot3 graphics} feature, see the documentation in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d} for its examples.
-
-\end{pgfplotskey}
-
\begin{pgfplotsxykey}{\x mode=\mchoice{normal,linear,log} (initially normal)}
Allows to choose between linear (=normal) or logarithmic axis scaling or logplots for each $x,y,z$-combination.
@@ -194,6 +230,15 @@ This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, com
\end{tikzpicture}
\end{codeexample}
+\begin{codeexample}[]
+\begin{tikzpicture}
+\begin{axis}[axis equal,small,view={45}{35.26}]
+\addplot3[mark=cube, blue, mark size=1cm]
+ coordinates {(0,0,0)};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
The configuration |axis equal=true| is actually just a style which sets |unit vector ratio=1 1 1,unit rescale keep size=true|.
\end{pgfplotskey}
@@ -252,53 +297,79 @@ This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, com
Trailing values of |1| can be omitted, i.e.\ |unit vector ratio=2 1| is the same as |unit vector ratio=2|; and |unit vector ratio=3 2 1| is the same as |unit vector ratio=3 2|.
An empty value |unit vector ratio={}| disables unit vector rescaling.
+ Note that an active |unit vector ratio| will implicitly set |scale mode=scale uniformly|\footnote{This has been introduced in version 1.6. For older versions, the axis equal feature produced wrong results for three--dimensional axes.}.
+
\begin{pgfplotskeylist}{%
unit vector ratio*=\marg{rx ry rz},
- unit rescale keep size=\marg{true,false} (initially true)}
+ unit rescale keep size=\mchoice{true,false,unless limits declared} (initially unless limits declared)}
In the default configuration, \PGFPlots\ maintains the original axis dimensions even though |unit vector ratio| involves different scalings.
+ \label{key:unit:rescale:keep:size}
It does so by enlarging the limits.
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=]
- \addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+ \addplot3[surf,z buffer=sort,samples=15,
+ variable=\u, variable y=\v,
+ domain=0:180, y domain=0:360]
+ ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=1 1 1]
- \addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+ \addplot3[surf,z buffer=sort,samples=15,
+ variable=\u, variable y=\v,
+ domain=0:180, y domain=0:360]
+ ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=0.25 0.5]
- \addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+ \addplot3[surf,z buffer=sort,samples=15,
+ variable=\u, variable y=\v,
+ domain=0:180, y domain=0:360]
+ ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
\end{axis}
\end{tikzpicture}
\end{codeexample}
\noindent The example above has the same plot, with three different unit ratios. The first has no limitations (it is the default configuration). The second uses the same length for each unit vector and enlarges the limits in order to maintain the same dimensions. The third example has an $x$ unit which is $\nicefrac14$ the length of a $z$ unit, and an $y$~unit which is $\nicefrac12$ the length of a $z$~unit.
+ \PGFPlots\ does its best to respect the involved scaling options (the prescribed |width| and |height|, the |unit vector ratio|, and any specified axis limits). In the case above, it enlarged the horizontal limits and kept the $z$~limit as-is. See |scale mode| and its documentation for details about the involved algorithm and its parameters.
+
The |unit rescale keep size=false| key, or, equivalently, |unit vector ratio*=...|, does not enlarge limits:
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,unit vector ratio=]
- \addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+ \addplot3[surf,z buffer=sort,samples=15,
+ variable=\u, variable y=\v,
+ domain=0:180, y domain=0:360]
+ ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,
unit rescale keep size=false,
unit vector ratio=1 1 1]
- \addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+ \addplot3[surf,z buffer=sort,samples=15,
+ variable=\u, variable y=\v,
+ domain=0:180, y domain=0:360]
+ ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
\end{axis}
\end{tikzpicture}
\begin{tikzpicture}
\begin{axis}[footnotesize,xlabel=$x$,ylabel=$y$,
unit vector ratio*=0.25 0.5, % the '*' implies 'unit rescale keep size=false'
]
- \addplot3[surf,samples=10,domain=0:1] {(1-x)*y};
+ \addplot3[surf,z buffer=sort,samples=15,
+ variable=\u, variable y=\v,
+ domain=0:180, y domain=0:360]
+ ({cos(u)*sin(v)}, {sin(u)*sin(v)}, {cos(v)});
\end{axis}
\end{tikzpicture}
\end{codeexample}
+ The key |unit rescale keep size| also affects |scale mode=scale uniformly| (which is closely related to |axis equal|).
+
+ Here is the reference of the value of |unit rescale keep size|: the value \declaretext{true} means that \PGFPlots\ will enlarge limits in order to keep the size. It will try to respect user provided limits, but if the user provided \emph{all} limits, it will \emph{override} the user-provided limits and will rescale them. Thus, |true| gives higher priority to the axis size than to user-provided limits. The choice \declaretext{false} will never rescale axis limits. The choice \declaretext{unless limits declared} is a mixture: it will enlarge limits unless the user provided them. If the user provides all limits explicitly, this choice is the same as |false|.
\end{pgfplotskeylist}
\end{pgfplotskey}
@@ -335,3 +406,224 @@ This feature is used to realize the \verbpdfref{\addplot3 graphics} feature, com
\end{tikzpicture}
\end{codeexample}
\end{pgfplotsxykeylist}
+
+\subsubsection{Scaling Descriptions: Predefined Styles}
+\label{sec:scaling:styles}
+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},
+ /pgfplots/try min ticks=\marg{integer},
+ /tikz/mark size=\marg{integer}}
+ These keys should be adjusted to the figure's dimensions. Use
+\begin{codeexample}[code only]
+\pgfplotsset{tick label style={font=\footnotesize},
+ label style={font=\small},
+ legend style={font=\small}
+}
+\end{codeexample}
+ to provide different fonts for different descriptions.
+
+ The keys |max space between ticks| and |try min ticks| are described on page~\pageref{maxspacebetweenticks} and configure the approximate distance and number of 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,
+ minor tick num=1,
+ legend entries={Leg}]
+ \addplot {max(4*x,7*x)};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+ The initial setting is
+\begin{codeexample}[code only]
+\pgfplotsset{
+ 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,
+ minor tick num=1,
+ legend entries={Leg}]
+ \addplot {x^2};
+ \end{axis}
+\end{tikzpicture}
+\end{codeexample}
+ The initial setting is
+\begin{codeexample}[code only]
+\pgfplotsset{
+ small/.style={
+ width=6.5cm,
+ height=,
+ tick label style={font=\footnotesize},
+ label style={font=\small},
+ 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,
+ minor tick num=1,
+ 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]
+\pgfplotsset{
+ footnotesize/.style={
+ width=5cm,
+ height=,
+ legend style={font=\footnotesize},
+ tick label style={font=\footnotesize},
+ label style={font=\small},
+ title style={font=\small},
+ every axis title shift=0pt,
+ max space between ticks=15,
+ every mark/.append style={mark size=8},
+ major tick length=0.1cm,
+ minor tick length=0.066cm,
+ },
+}
+\end{codeexample}
+As for |small|, it can be convenient to set |footnotesize| and set |width| afterwards.
+
+You will need |compat=1.3| or newer for this to work.
+\end{stylekey}
+
+\begin{stylekey}{/pgfplots/tiny}
+ Redefines several keys such that the axis is very small. Most descriptions will have |\tiny| as fontsize.
+
+\begin{codeexample}[]
+\begin{tikzpicture}
+ \begin{axis}[tiny,
+ title=A ``tiny'' figure,
+ xlabel=The $x$ axis,
+ ylabel=The $y$ axis,
+ minor tick num=1,
+ 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]
+\pgfplotsset{
+ tiny/.style={
+ width=4cm,
+ height=,
+ legend style={font=\tiny},
+ tick label style={font=\tiny},
+ label style={font=\tiny},
+ title style={font=\footnotesize},
+ every axis title shift=0pt,
+ max space between ticks=12,
+ every mark/.append style={mark size=6},
+ major tick length=0.1cm,
+ minor tick length=0.066cm,
+ every legend image post/.append style={scale=0.8},
+ },
+}
+\end{codeexample}
+As for |small|, it can be convenient to use |tiny,width=4.5cm| to adjust the width.
+
+You will need |compat=1.3| or newer for this to work.
+\end{stylekey}
+
+
+\subsubsection{Scaling Strategies}
+ The content of this section is quite involved -- and its knowledge is typically unnecessary because by default, \PGFPlots\ controls the involved stuff automatically. You may want to skip this section.
+
+\begin{pgfplotskey}{scale mode=\mchoice{auto,none,stretch to fill,scale uniformly} (initially auto)}
+ Specifies how to choose the (individual) unit vector scaling factors, their length ratios, and perhaps the axis limits in order to fill the prescribed |width| and |height|.
+
+ The |scale mode| implementation expects some ``initial'' set of unit vectors. This initial set of unit vectors is determined as follows: for standard two--dimensional axes, it is simply the unit cube $e_x=(1\text{pt},0\text{pt})^T$, $e_y=(0\text{pt},1\text{pt})^T$, $e_z=0$. For three--dimensional axes, it is the outcome of the two keys |view| and |plot box ratio|. If you provided units explicitly by means of one of |x|, |y|, or |z|, this value is the initial unit vector.
+
+ In addition, it expects ``initial'' axis limits (i.e.\ values of |xmin|, |xmax|, etc.). The initial axis limits are those limits which have been deduced from your data or which have been provided explicitly. Furthermore, the initial axis limits already include changes of the |enlargelimits| key.
+
+ Given the initial set of unit vectors and the initial axis limits, the |scale mode| implementation is a kind of ``post--processor'' which creates modified unit vectors and modified axis limits in order to satisfy all specified constraints. These constraints are |width|, |height|, and |unit vector ratio|.
+
+ The initial choice \declaretext{auto} tells \PGFPlots\ to take full control over this key. It chooses one of the other possible choices depending on the actual context. The choice |auto| evaluates to |scale uniformly| if |unit vector ratio| is set. Otherwise it evaluates to |stretch to fill|.
+
+ The choice \declaretext{none} does not apply any rescaling at all. Use this if prescribed lengths of |x|, |y| (and perhaps |z|) should be used. In other words: it ignores |width| and |height|. In this case, you may want to set |x post scale| and its variants to rescale units manually. See also |disabledatascaling|.
+
+ The choice \declaretext{stretch to fill} takes the initial unit vectors and rescales the unit vectors with two \emph{separate} scales: one which results in the proper |width| and one which results in the proper |height|. As a consequence, the unit vectors are modified and distorted such that the final image fits into the prescribed dimensions. This is usually what one expects unless one provides unit directions explicitly. This mode does not change axis limits. Note that if one of the unit vectors has been provided explicitly, \PGFPlots\ will not change it. It will only change the remaining axis limits. This mode contradicts |axis equal| or |unit vector ratio|.
+
+ The choice \declaretext{scale uniformly} takes the initial unit vectors and applies only \emph{one} scaling factor to all units. In this case, there is just \emph{one} common scaling factor for both |width| and |height|. Naturally, this will result in unsatisfactory results because either the final width or the final height will not be met. Therefore, this choice will adjust axis limits to get the desired dimensions. Thus, the unit vectors have exactly the same size \emph{relations and angles} as they had before the scaling; only their magnitude is changed uniformly. In addition, axis limits may be changed (with individual scaling factors for each axis limit). Note that if unit vectors have been provided explicitly, \PGFPlots\ can still rescale it with this choice -- it will keep the relative directions and size ratios. The choice |scale uniformly| tries its best to modify the degrees of freedom in a ``useful'' way. The precise meaning of ``useful'' is the |scale uniformly strategy| key.
+
+ \begin{pgfplotskey}{scale uniformly strategy=\mchoice{auto,units only,change vertical limits,\\change horizontal limits} (initially auto)}
+ The |scale uniformly| method requires to determine one \emph{common} scaling factor which rescales every axis \emph{unit}. In addition, it allows one scaling factor \emph{for each axis limit}, i.e.\ up to three.
+
+ The constraints for this search are that we want to satisfy the |width|/|height| constraint, have as few rescaling as possible and that we do not want to reduce limits (as this could possibly hide data points).
+
+ The choice \declaretext{auto} chooses one of the other possibilities automatically. Depending on whether we have two dimensions or three dimensions, it compares the available methods and chooses the one which does not reduce limits and which involves the fewest rescaling (i.e.\ it may compare the outcome of the other strategies). This is the default. If you keep the choice |auto|, you do not have to worry about the remaining choices. Note that manually provided axis limits will not be modified.
+
+ The choice \declaretext{units only} will not enlarge axis limits. It will only rescale the units. To this end, it chooses the scaling factor such that the \emph{smaller} target dimension is filled as desired. In other words: if |width| $< $ |height|, it will scale to satisfy the |width| constraint. The |height| constraint will be ignored. The case $>$ will be done the other way round. The choice |units only| typically results in a square axis as it takes the initial set of unit vectors (which are typically the unit box) and scales them with a common scaling factor. Consequently, you can choose |units only| if you want a boxed axis. You can still change axis limits manually, however.
+
+ The choice \declaretext{change vertical limits} chooses a common scaling factor for the unit vectors on order to satisfy the |width| (!) constraint. This common scaling factor is similar to |units only| -- but |units only| can also decide to satisfy the |height| constraint whereas |change vertical limits| will scale unit vectors to satisfy |width|. In order to satisfy the |height| constraint, |change vertical limits| modifies just the vertical limits. For two--dimensional axes, this is |ymin| and |ymax|. For three--dimensional axes, this is |zmin| and |zmax|. Clearly, there is a chance that it will \emph{decrease} the displayed range -- in this case, parts of the image will be clipped away. This method \emph{assumes} that the vertical axis has not been rotated (i.e.\ that $e_{yx}=0$ or $e_{zx}=0$, respectively). It refuses to work and falls back to |units only| for rotates axes. Choose |change vertical limits| if you want the image (i.e.\ the actual content) as wide as possible. You can modify |width| and |height| to improve its outcome. Note that manually specified axis limits will not be changed, see below for details.
+
+ The choice \declaretext{change horizontal limits} attempts a similar approach, but for the horizontal limits: it determines one suitable scaling factor which is applied to all unit vectors and modifies horizontal axis limits to satisfy the remaining constraints. For two--dimensional axes, this is quite simple because we typically have $e_{xy} = 0$ (i.e.\ the $x$ unit vector has vanishing $y$ component) and $e_{yx}=0$ such that \PGFPlots\ can change axis limits easily. If a two--dimensional axis has an $x$ unit with $e_{xy} \neq 0$, the method is not applicable and falls back to |units only|. For three--dimensional axes, it assumes that the $z$ vector is not rotated, i.e.\ $e_{zy} = 0$ and tries to change limits for both $x$ and $y$. This choice is much more involved because here, $x$ and $y$ components are coupled. Consequently, the common unit scaling factor and the two involved axis limit compensation factors for $x$ and $y$ are tightly coupled as well. \PGFPlots\ solves a system of non--linear equations iteratively to arrive at a suitable solution for all three scalings. Use this method if |change vertical limits| would clip away parts of the image (because it reduced the displayed range) and you do not want to change |width| and |height|. The choice |change horizontal limits| will typically result in more empty space in the resulting figure. But it will not clip away content. Manually specified axis limits will not be changed, see below for details.
+
+ \end{pgfplotskey}
+
+ \paragraph{Manually provided axis limits:} Any manually provided arguments for |xmin| and its variants are considered to be immutable; \PGFPlots\ will not change them. If you assign |xmin|, \PGFPlots\ will only change |xmax| and vice--versa. If you assign both |xmin| and |xmax|, \PGFPlots\ will not change $x$~limits at all. Note that if you assign both |xmin| and |xmax|, \PGFPlots\ will simply skip the scaling and will give up on the constraints. It will not try to compensate the lack of scaling opportunities by changing $y$~limits, for example. This has the positive effect that assigning limits does not change the complete appearance of your axis. The allowed set of changes to axis limits can be configured with the following key.
+
+ \paragraph{Interaction with }|enlargelimits|: Note that |enlargelimits| and |scale mode| are independent of another: the outcome of |enlargelimits| is used as ``initial axis limits'' and these limits may be changed by |scale mode| (even if you said |enlargelimits=false|). See the documentation of |enlargelimits| for details on this interaction.
+
+ \begin{pgfplotskey}{
+ unit rescale keep size=\mchoice{true,false,unless limits declared} (initially unless limits declared)}
+ In the default configuration \declaretext{unless limits declared}, unit rescaling may cause changes to the axis limits in order to keep the figure's size intact. However, only those limits which have not been declared manually are subject to rescaling: if you say |xmin=1|, only |xmax| and the limits for $y$ and $z$ are free to change.
+
+ Setting |unit rescale keep size=|\declaretext{false} will \emph{disable} the modification of axis limits altogether, i.e.\ axis limits will not be rescaled to compensate scalings on unit vectors.
+
+ Setting |unit rescale keep size=|\declaretext{true} will always rescale limits, even if they have been declared manually.
+
+ This key mainly affects |scale mode=scale uniformly|. This, in turn, is used for |axis equal| and |\addplot3 graphics|.
+
+ See also the addition documentation for this key and related examples on page~\pageref{key:unit:rescale:keep:size}.
+ \end{pgfplotskey}
+
+ The |scale uniformly| choice is implicitly used for |axis equal| and for the \verbpdfref{\addplot3 graphics} feature, see the documentation in Section~\ref{sec:plotgraphics3d} on page~\pageref{sec:plotgraphics3d} for its examples. Note that the common case is that the initial unit vectors form the unit cube (i.e.\ those before scaling, see above). In this case, |scale uniformly| is the same as |axis equal|.
+\end{pgfplotskey}
+
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-27 03:00:13 +0000