diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex new file mode 100644 index 00000000000..7d217a22b3a --- /dev/null +++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex @@ -0,0 +1,176 @@ +\subsection{Units in Labels} +\label{sec:units} + +{\noindent {\emph{by Nick Papior Andersen}}} + +\begin{pgfplotslibrary}{units} + A library which allows to use automatic typesetting of units in labels. The library utilizes different keys to typeset the final output in a consistent way. + Calling one of the commands automatically sets the key `|use units=true|' so one has not to worry of this. +\end{pgfplotslibrary} +\PGFPlots\ has the capability of supporting units. This provides quick customization of the plot as well as the addition of units in labels. + +Loading the library automatically enables the typesetting of units in labels. Currently it only supports predefined SI units but a per-user customization is also +implemented such that it can be used in any way you like. + +First the key which enables you to switch on/off the unit system. +\begin{pgfplotskey}{use units=\marg{boolean} (initially true)} + This key simply enables \PGFPlots\ to use what is described next. This key will be set to true if you load the library. You can use this to temporarily + determine whether the unit library should be used in plots. +\end{pgfplotskey} +\begin{pgfplotsxykey}{\x\ unit=\marg{unit} (initially empty)} + These keys sets the unit in their respective axis. In SI units you could for instance set the |x unit| in Newton as |x unit=N|. +\end{pgfplotsxykey} +\begin{pgfplotsxykey}{\x\ unit prefix=\marg{prefix} (initially empty)} + These keys sets the prefix of the unit. If a value on the |y axis| is in kilo you would set the |y unit prefix=k|. Prefix will be typeset in front of the unit. + + This command will not intervene with the basis of the axis system. I.e. a prefix as just mentioned will not divide every |y axis| number by 1000. + In order to do this see key \meta{axis}| SI prefix|, see Section \ref{sec:SI:prefix}. + + Notice that if the \meta{axis}| unit| isn't set the entire unit will not be typeset. + + \paragraph{Remarks:} Remember that all typesetting of labels occur within a \$\$ environment. Therefore one can use \textbackslash|frac| + and other mathematics commands. +\end{pgfplotsxykey} +Often one just have to utilize the above mentioned keys. It is the basis of the unit typesetting system provided by \PGFPlots. +% \usepgfplotslibrary{units} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[use units, + x unit=m,x unit prefix=k, + y unit=N,y unit prefix=m, + xlabel=Distance,ylabel=Force] + \addplot coordinates { + (1,2.3) + (2,2.7) + (3,2.1) + (4,1.8) + (5,1.5) + (6,1.1) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + +Below is an example of what would be yielded according to the styles +\begin{codeexample}[code only] +% x label becomes ``Temperature [T]'', y label becomes ``Nothing'' +\pgfplotsset{use units,x unit=T,xlabel=Temperature,ylabel=Nothing} +% x label becomes ``Temperature'', y label becomes ``Nothing'' +\pgfplotsset{use units,x unit prefix=m,xlabel=Temperature,ylabel=Nothing} +\end{codeexample} +Notice the second example. Only setting the prefix will not activate the unit typesetting. Therefore one should ensure to use the |x unit| key if the +typesetting of the labels should be done. + +For typesetting the units one can also change the appearance. For instance one might not like the square brackets which surround the unit. These can +luckily be changed using the below keys. +\begin{pgfplotskeylist}{unit marking pre=\marg{pre} (initially \textbackslash left[),unit marking post=\marg{post} (initially \textbackslash right]),unit markings=\mchoice{parenthesis,square brackets,slash space} (initially square brackets)} + These keys sets the surroundings of the unit. The initial yields $\left[\frac{1}{2}\right]$ such that you can typeset fractions in units. Be aware that + you can only obtain large fractions if you use \textbackslash|dfrac|. These can easily be set using the option key |unit markings| where the options typesets as the following +\begin{codeexample}[code only] +\pgfplotsset{x unit=T,unit markings=parenthesis} % x unit becomes `` \left(T\right)'' +\pgfplotsset{x unit=T,unit markings=square brackets} % x unit becomes `` \left[T\right]'' +\pgfplotsset{x unit=T,unit markings=slash space} % x unit becomes `` / T'' +\end{codeexample} + Notice that all typesetting of units first inserts a space and then the |unit marking pre| code. + + Of course you can just manually set each of them with the |unit marking pre| and |unit marking post| keys. Just remember that they are typeset within a \$\$. +\end{pgfplotskeylist} + +One will typically typeset the unit with a specific font. To do so an option of changing the typesetting command is supplied. +\begin{pgfplotscodetwokey}{unit code}%\textbackslash mathrm\{\})} + This can be utilized to great extend. As a default the typesetting of the units is as |\mathrm{|\meta{unit prefix}\meta{unit}|}|. But if one for instance + wishes to utilize the package |siunitx|, which has great capabilities in typesetting both units, numbers and angles, one can just set the key as +\begin{codeexample}[code only] +\pgfplotsset{unit code/.code 2 args={\si{#1#2}}} +\end{codeexample} + which would yield the unit as |\si{|\meta{unit prefix}\meta{unit}|}|. + + The first argument is typeset as \meta{unit prefix} and the second argument is \meta{unit}. + + The most important thing is that the command needs exactly two arguments. So if you would like a command that typesets the prefix in bold face and the + unit in normal roman font you should call +\begin{codeexample}[code only] +\pgfplotsset{unit code/.code 2 args={\mathbf{#1}\mathrm{#2}} +\end{codeexample} +\end{pgfplotscodetwokey} + + +\subsubsection{Preset SI prefixes} +\label{sec:SI:prefix} +\index{prefixes!unit} +To support the SI system a number of preset keys are defined. This should yield a more intuitive way of supplying the prefix as well as add some more +functionality. For instance it provides an easy scaling mechanism. +\begin{pgfplotsxykeylist}{\x\ SI prefix=\mchoice{yocto,\dots,milli,centi,deci,deca,hecto,kilo,\dots,yotta} (initially none), + change \x\ base=\mchoice{true,false} (initially false)} + These keys sets the prefix of the unit. The allowed prefixes are: + + \begin{center} + \begin{tabular}{>{\ttfamily}c>{$}c<{$}} + \toprule + \rm Prefix & $Power$\\ + \midrule + yocto & -24\\ + zepto & -21\\ + atto & -18\\ + femto & -15\\ + pico & -12\\ + nano& -9\\ + micro & -6\\ + milli & -3\\ + centi& -2\\ + deci& -1\\ + \bottomrule + \end{tabular}\qquad\qquad + \begin{tabular}{>{\ttfamily}cc} + \toprule + \rm Prefix & Power\\ + \midrule + deca & 1\\ + hecto & 2\\ + kilo & 3\\ + mega & 6\\ + giga & 9\\ + tera& 12\\ + peta & 15\\ + exa & 18\\ + zetta& 21\\ + yotta& 24\\ + \bottomrule + \end{tabular} + \end{center} + + As well as resetting the base of the axis if the key |change |\meta{axis}| base=true|. Just \textbf{remember} to + set the |change |\meta{axis}| base| before using the \meta{axis}| SI prefix| key. + + See the utilization as in the example below. +% \usepgfplotslibrary{units} +\begin{codeexample}[] +\begin{tikzpicture} + \begin{axis}[change x base, + x SI prefix=kilo,x unit=m, + y SI prefix=milli,y unit=N, + xlabel=Distance,ylabel=Force] + \addplot coordinates { + (1000,1) + (2000,1.1) + (3000,1.2) + (4000,1.3) + }; + \end{axis} +\end{tikzpicture} +\end{codeexample} + Notice that the |x axis| has changed base without displaying the $\cdot 10^{3}$. This is done by using the key |change x base|. Even though you have used + the key |y SI prefix=milli| the base isn't changed on the |y axis|. Try adding |change y base| just after |change x base| and see the result! +\end{pgfplotsxykeylist} + +The above keys are the easy implementation of the base change. Below is a further customization of the base change. It makes it easy to implement a prefix +with a custom base change. + +\begin{pgfplotskey}{axis base prefix={axis \marg{axis} base \marg{base} prefix \marg{prefix}} (initially empty)} + One can utilize this key to customize further of the base and setting the prefix. +\begin{codeexample}[code only] +\pgfplotsset{change x base,axis base prefix={axis x base -3 prefix k}} +\pgfplotsset{change x base,x SI prefix=kilo} +\end{codeexample} + The above two commands are thus equivalent. Remember that the base should operate in opposite of prefix! +\end{pgfplotskey} |