summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.libs.units.tex
diff options
context:
space:
mode:
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.tex176
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}