
\section{Symbolic Coordinates and User Transformations}
\label{pgfplots:sec:symbolic:coords}

\PGFPlots{} supports user transformations which can be applied to input and
output coordinates. Suppose the plot shall display days versus account
statements over time. Then, one wants to visualize date versus credit balance.
But: dates need to be transformed to numbers before doing so! Furthermore, tick
labels shall be displayed as dates as well. This, and more general
transformations, can be implemented using the |x coord trafo| and
|y coord trafo| keys.


\paragraph{Remark:}

This section applies to users who want to have non-standard input
\emph{coordinates}. If you have normal numbers which don't need to be
transformed and you like to have special symbols as tick labels, you should
consider using the |xticklabels| (|yticklabels|) key described on
page~\pageref{pgfplots:key:xticklabels}.

See also Section~\ref{sec:transformation:interaction} for different types of
transformations and their interaction.

\begin{pgfplotsxycodekeylist}{%
    \x\ coord trafo,
    \x\ coord inv trafo%
}
    These code keys allow arbitrary coordinate transformations which are
    applied to input coordinates and output tick labels.

    The |x coord trafo| and |y coord trafo| command keys take one argument
    which is the input coordinate. They are expected to set |\pgfmathresult| to
    the final value.

    At this level, the input coordinate is provided as it is found in the
    |\addplot| statement. For example, if $x$ coordinates are actually of the
    form \meta{year}-\meta{month}-\meta{day}, for example |2008-01-05|, then a
    useful coordinate transformation would transform this string into a number
    (see below for a predefined realization).

    In short, \emph{no} numerics has been applied to input coordinates when
    this transformation is applied.\footnote{Of course, if coordinates have been
    generated by gnuplot or \pgfname{}, this does no longer hold.}

    The input coordinate transformation is applied to
    %
    \begin{itemize}
        \item any input coordinates (specified with |\addplot| or |axis cs|),
        \item any user-specified |xtick| or |ytick| options,
        \item any user-specified |extra x ticks| and |extra y ticks| options,
        \item any user-specified axis limits like |xmin| and |xmax|.
    \end{itemize}

    The output coordinate transformation |x coord inv trafo| is applied to tick
    positions just before evaluating the |xticklabel| and |yticklabel| keys.
    The argument to |x coord inv trafo| is a fixed point number (which may have
    trailing zeros after the period). The tick label code may use additional
    macros defined by the inverse transformation.

    Remark: \PGFPlots{} will continue to produce tick positions as usual, no
    extra magic is applied. It may be necessary to provide tick positions
    explicitly if the default doesn't respect the coordinate space properly.

    The initial value of these keys is
    %
\begin{codeexample}[code only]
\pgfplotsset{
    x coord trafo/.code={},
    x coord inv trafo/.code={},
}
\end{codeexample}
    %
    \noindent which simply disables the transformation (the same for $y$, of
    course).


    \paragraph{Remark:}

    It might be necessary to set
    %
\begin{codeexample}[code only]
\pgfplotsset{
    xticklabel={\tick},
    scaled x ticks=false,
    plot coordinates/math parser=false,
}
\end{codeexample}
    %
    \noindent in order to avoid number formatting routines on |\tick| or
    numerics for tick scale methods. This is done automatically by the
    predefined symbolic coordinate styles (see below).
\end{pgfplotsxycodekeylist}


\subsection{String Symbols as Input Coordinates}

It is possible to provide a string dictionary to \PGFPlots{}. An input
coordinate can then use any symbol provided in that dictionary.

\begin{pgfplotsxykeylist}{symbolic \x\space coords=\marg{dictionary}}
    A style which sets |x coord trafo| and |x coord inv trafo| (or the
    respective |y| or |z| variants) such that any element in \meta{dictionary}
    is a valid input coordinate. The \meta{dictionary} can be a comma separated
    list or a list terminated with `|\\|'. In both cases, white space is
    considered to be part of the names (use `|%|' at end of lines).

    The dictionary will assign integer numbers to every element (starting with
    $0$). These integers are used internally for arithmetics. Finally, the
    inverse transformation takes a fixed point number and maps it to the
    nearest integer, and that integer is mapped into the dictionary.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    symbolic x coords={a,b,c,d,e,f,g,h,i},
]
    \addplot+ [smooth] coordinates {
        (a,42)
        (b,50)
        (c,80)
        (f,60)
        (g,62)
        (i,90)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}

    The effect of the transformation is simply that input coordinates can be
    elements of the dictionary and tick labels will be chosen out of this
    dictionary as well.

    Note that |symbolic x coords| is more or less equivalent to explicitly
    provided |xtick| positions and |xticklabels|:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    xtick={0,1,2,...,20},
    xticklabels={a,b,c,d,e,f,g,h,i},
    xticklabel style={
        anchor=base,
        yshift=-\baselineskip,
    },
]
    \addplot+ [smooth] coordinates {
        (0,42)
        (1,50)
        (2,80)
        (5,60)
        (6,62)
        (8,90)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent The difference is that the approach with |symbolic x coords| is
    simpler to read whereas the |xtick| approach is simpler with respect to
    coordinate arithmetics (for example to increase limits using
    |enlargelimits|). The |xticklabel style| here is an attempt to align all
    tick labels at their base line (which would be useful for
    |symbolic x coords| as well as soon as labels have characters which exceed
    the baseline).

    The key |symbolic x coords| and its variants accepts a comma-separated list
    of strings. These can be arbitrary and can even contain unexpandable
    material:\footnote{As of \PGFPlots{} version 1.11.}
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    symbolic x coords={a,$1 \pm 2$,c,d,1\&1,f,g,h,i},
    xtick=data,
]
    \addplot+ [smooth] coordinates {
        (a,42)
        ($1 \pm 2$,50)
        (c,80)
        (1\&1,60)
        (g,62)
        (i,90)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    In any case, the arguments of \meta{dictionary} must be met precisely,
    including any white spaces.

    Symbolic coords are useful since they reduce the burden to map strings to
    indices and vice versa. However, they have a caveat: what if you want to
    set |xmin| to something to the left of the first |symbolic x coord|? This
    is impossible since any input coordinate is expected to be contained in
    |symbolic x coord|. To allow such modifications nevertheless, \PGFPlots{}
    checks for the magic prefix\index{Symbolic coords![normalized]}
    \declareandlabel{[normalized]}:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    symbolic x coords={a,b,c,d,e,f,g,h,i},
    xmin={[normalized]-1.7},
    minor tick num=1,
]
    \addplot+ [smooth] coordinates {
        (a,42)
        (b,50)
        (c,80)
        (f,60)
        (g,62)
        (i,90)};

    \fill (axis cs:{[normalized]1.5},60)
        circle (2pt) coordinate [pin={$1.5$}];
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    Whenever \PGFPlots{} finds a symbolic coordinate which starts with the
    precise string `|[normalized]|', it will interpret everything after the
    prefix to be a normalized number and \emph{no} symbol. In our example,
    |xmin| will be set to $-1.7$, i.e.\@ something to the left of $a$ (which
    would be $0$ according to the definition above). Furthermore, the custom
    |\node| is placed at $(1.5,60)$ despite the fact the $1.5$ is no defined
    symbol -- but we know that it is between |b| and |c| which are dictionary
    entry $1$ and $2$, respectively.


    \paragraph{See also}

    the option to add tick and/or grid lines at every encountered coordinate
    using |xtick=data| (or |minor xtick=data|).
\end{pgfplotsxykeylist}


\subsection{Dates as Input Coordinates}
\label{pgfplots:sec:date:coords}

{
\def\pgfplotsmanualcurlibrary{dateplot}

The already mentioned application of using dates as input coordinates has been
predefined, together with support for hours and minutes. It relies on the
\pgfname{} calendar library which converts dates to numbers in the Julian
calendar. Then, one coordinate unit is one day.

\begin{pgfplotslibrary}{dateplot}
    Loads the coordinate transformation code.
\end{pgfplotslibrary}

\begin{stylekey}{/pgfplots/date coordinates in=\meta{coordinate}}
    Installs |x coord trafo| and |x coord inv trafo| (or the respective variant
    for \meta{coordinate}) such that ISO dates of the form
    \meta{year}|-|\meta{month}|-|\meta{day} are accepted. Here,
    \meta{coordinate} is usually one of |x|, |y|, or |z|, but it can also
    contain stuff like |hist/data|.

    After installing this style, input values like |2006-02-28| will be
    converted to an ``appropriate'' integer using the Julian calender. Input
    coordinates may be of the form

        \meta{year}|-|\meta{month}|-|\meta{day}

    \noindent or they may contain times as

        \meta{year}|-|\meta{month}|-|\meta{day} \meta{hour}|:|\meta{minute}.

    The result of the transformation are numbers where one unit is one day and
    times are fractional numbers.

    The transformation is implemented using the \pgfname-calendar module, see
    \cite[Calendar Library]{tikz}. This reference also contains more
    information about extended syntax options for dates.

    The inverse transformation provides the following macros which are
    available during tick label evaluation (i.e.\@ when used inside of
    |xticklabel| or |yticklabel|):
    %
    \begin{itemize}
        \item \declareandlabel{\year} expands to the year component,
        \item \declareandlabel{\month} expands to the month component,
        \item \declareandlabel{\day} expands to the day component,
        \item \declareandlabel{\hour} expands to the hour component (using
            two digits),
        \item \declareandlabel{\Hour} expands to the hour component (but
            omits leading zeros),
        \item \declareandlabel{\minute} expands to the minute component (two
            digits),
        \item \declareandlabel{\Minute} expands to the minute component
            (omits leadings zeros),
        \item \declareandlabel{\lowlevel} expands to the low level number
            representing the tick,
        \item \declareandlabel{\second} will always be |00|.
    \end{itemize}
    %
    This allows to use |\day.\month.\year| or |\day. \hour:\minute| inside of
    |xticklabel|, for example.

    A complete example (with fictional data) is shown below.
    %
\pgfplotsset{anchor=center,/tikz/every picture/.append style={baseline}}
% \usepgfplotslibrary{dateplot}\usepackage{eurosym}
\begin{codeexample}[]
% requires \usepgfplotslibrary{dateplot} !

\pgfplotstabletypeset[string type]{plotdata/accounts.dat}

\begin{tikzpicture}
    \begin{axis}[
        date coordinates in=x,
        xticklabel={\day.\month.},
        xlabel={2008},
        stack plots=y,
        yticklabel={\pgfmathprintnumber{\tick}\EUR{}}, % <- requires \usepackage{eurosym}
        ylabel=Total credit,
        ylabel style={yshift=10pt},
        legend style={
            at={(0.5,-0.3)},anchor=north,legend columns=-1,
        },
    ]
        \addplot table [x=date,y=account1] {plotdata/accounts.dat};
        \addplot table [x=date,y=account2] {plotdata/accounts.dat};
        \addplot table [x=date,y=account3] {plotdata/accounts.dat};
        \legend{Giro,Tagesgeld,Sparbuch}
    \end{axis}
\end{tikzpicture}
\end{codeexample}

% \usepgfplotslibrary{dateplot}\usepackage{eurosym}
\begin{codeexample}[]
% requires \usepgfplotslibrary{dateplot} !
\begin{tikzpicture}
\begin{axis}[
    date coordinates in=x,
    xtick=data,
    xticklabel style=
        {rotate=90,anchor=near xticklabel},
    xticklabel=\day. \hour:\minute,
]
    \addplot coordinates {
        (2009-08-18 09:00,  050)
        (2009-08-18 12:00,  100)
        (2009-08-18 15:00,  100)
        (2009-08-18 18:35,  100)
        (2009-08-18 21:30,  040)
        (2009-08-19,        020)
        (2009-08-19 3:00,   000)
        (2009-08-19 6:0,    035)
    };
\end{axis}
\end{tikzpicture}
\end{codeexample}
\end{stylekey}

\begin{pgfplotskey}{date ZERO=\meta{year}-\meta{month}-\meta{day}}
    A technical key which defines the $0$ coordinate of |date coordinates in|.

    \PGFPlots{} up to and including version 1.12 required this value. As of
    version 1.13, the first encountered coordinate is used as |date ZERO|,
    i.e.\@ it is assigned automatically without user intervention.

    Users will never see the resulting numbers, so one probably never needs to
    change this value. This key allows to set the result as needed.
\end{pgfplotskey}

}
