Keeping documentation up-to-date using LaTeX and TikZ

This post is based on a recent problem I encountered while working on an academic question. We had a frequently changing set of input cases, each describing a specific transportation problem’s layout. The cases were sent to an algorithm chain and discussed within the technical documentation. To prevent stale data from entering the report, we wanted to create a solution that would use the input files used for the algorithm to be the source for the report, thus having a single truth source. The goal was to replicate the following illustration using only a CSV file containing the coordinates and types of the nodes using LaTeX and PGF/TikZ. (LaTeX is a wordprocessor and markup language that focuses strongly on separating content and layout while TikZ allows for the creation of vector graphics within LaTex using a descriptive language.)

The goal

Set next to each other, the network allows a quick overview of the case’s design, while the table gives more detailed information.

Creating the table

For creating the table based on the data we can use the csvsimple package using its csvreader function. The parameters given style the table in the desired booktabs layout. To simplify the usage, this function is then wrapped within a macro, which takes the name of the data file read.

\newcommand{\renderTable}[1]{

    \csvreader[
        separator=tab,
        tabular=rlr,
        table foot=\bottomrule,
        after table=\\\vspace{0.2cm}\footnotesize$\dagger$ Demand or supply depending on type,
        table head=\toprule Id & Type & Amount$^\dagger$\\\midrule
    ]
    {figures/##1.tsv}
    {1=\id,2=\x,3=\y,4=\type,5=\amount}
    {\id & \type & \amount}%

}

Drawing the network

Drawing the network is not that much more difficult if we use the already descriptive TikZ. Just as a quick, refresher: Using commands directly within the tikzpicture environment in LaTeX, we can draw vector graphics. For example, we can use the following code to draw two nodes and to connect them with a line:

\begin{tikzpicture}
\node (n1) at (0,0) {Node1};
\node (n2) at (4,0) {Node2};
\draw (n1) -- (n2);
\end{tikzpicture}

As the TikZ code is embedded within the LaTeX code, any LaTex macro or plugin can be written, thus allowing us to use the csvsimple package again. If called without any styles, it simply processes the content given to it. The only problem left to solve is that TikZ does not allow changing the drawing order but instead always draws objects in the order that they appear. The quick fix used here is to simply read the data multiple times, once for each desired layer; First, define all coordinates, then draw the links between them and finally the nodes themselves. While this might create performance troubles with larger files, it is entirely sufficient for this use case.

\begin{tikzpicture}
\csvreader[separator=tab]{figures/##1.tsv}{1=\id,2=\x,3=\y,4=\type,5=\amount}{
    % define coordinate 
    \coordinate (\id) at (\x,\y);
}
\csvreader[separator=tab]{figures/##1.tsv}{1=\id,2=\x,3=\y,4=\type,5=\amount}{
    % link previous nodes to this node
    \foreach \destination in {0,...,\id}
        \draw[nodeLink] (\destination) -- (\id);
}
\csvreader[separator=tab]{figures/##1.tsv}{1=\id,2=\x,3=\y,4=\type,5=\amount}{
    % draw node with style
    \node[\type Node] (n\id) at (\id) {\id};

}
\end{tikzpicture}

This code is refactored into a macro, which can be used within a tikzpicture environment. As the named coordinates and nodes are available within the environment, any further drawing calls can reference them.

Conclusion

This again shows the extreme flexibility that the LaTeX environment allows in regard to technical documentation. Using just a few standard packages has allowed us to turn a static file into a dynamic document that updates itself on every compilation.

Even without the automation, creating the graph was much easier in TikZ than in any other design program. I recommend reading the full documentation to learn more about its possibilities. For more complex data-driven charts, the use of pfgplots is highly recommended.