\section{Units in Labels}
\label{sec:units}

{\noindent {\emph{by Nick Papior Andersen}}}

\begin{pgfplotslibrary}{units}
\index{Tick Labels!Units (km, m, etc)}%
  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 does not have to worry about 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 set 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 set 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 math mode (i.e.\ within \$\$ delimiters). Therefore one can use \textbackslash|frac|
  and other mathematics commands.
\end{pgfplotsxykey}
Often one just has 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 obtained 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 set 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 extent. By default, units are typeset 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}


\subsection{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}
