Procedurally generated diagrams

Of the kind I need, a practical guide to the creation thereof

March 2, 2015 — February 17, 2024

diagrams generated via text rather than point-and-click.

Figure 1

Python, R, julia, javascript, among others, all have diverse plotting infrastructure, some of which turns out to also be diagramming infrastructure. In practice I often generate part of a diagram this way, but rarely the whole thing.

The major distinction in the category of tools seems to be between whether they automate layout entirely, removing control, or they completely fail to assist with layout at all, requiring the henous manual control. The tools that lie in the middle, which make layout easy but not automatic, are the ones that it turns out help me most in practice.

1 Tools That Automate Just Enough But Have Other Difficulties

1.1 TikZ/pstricks/PGFplots

The classic type-your-diagram-in-then-work-out-what-went-wrong option. If I am constructing a well-understood type of diagram (e.g. a PGM) then this is good. If we are doing something unusual, it can become tedious. However, ChatGPT is very good at writing TikZ, and that is what I usually use.

The main strength of TikZ compared to other text-to-diagram things is that it has flexible ways of declaring layouts. Alternative tools prefer automatic layouts, which sounds like a good idea, but in empirically has never actually been what I want in the end, when I am trying to draw a diagram that uses spatial information to convey things.

The original flavour, pstricks/TikZ, is based on postscript and has compatibility problems with modern toolchains Modern projects seem to prefer the more compatible (less powerful ?) PGF/TikZ.

latexdraw is a Java pstricks GUI. Might be good, but I couldn’t install it.

TikZiT, looks like a reasonably good alternative GUI (HT Luis Riera Garcia for showing me this)

a super simple GUI editor for graphs and string diagrams. Its native file format is a subset of PGF/TikZ, which means TikZiT files can be included directly in papers typeset using LaTeX.

Agustinus Kristiadi, in The Last Mile of Creating Publication-Ready Plots introduces texworld/tikZplotlib, a matplotlib backend.

The overleaf tutorial, LaTeX Graphics using TikZ, is probably the best one.

I am currently trying to render TikZ in quarto using a plug in that I am writing: danmackinlay/quarto_tikz.

1.2 Cetz

Cetz reimagines Tikz for LatTeX competitor, Typst.

1.3 Grammar of graphics

I am slightly interested in a certain kind of low-key automation which is sometimes useful in diagrams, which I understand is called a “compositional layout” diagramming style, as seen in Grammar-of-graphics tools, most famously R’s ggplot2. These tools lay out components as a kind of algebra of composed styling operations.

Compose.jl provides these for Julia. Diagrams is the Haskell version. R’s grid is purportedly somewhat similar for layout, as is all the ggplot2 stuff for style.

I love that idea, although the tools just mentioned do not seem to be awesome at diagramming graphical models, which is what I wanted.

2 Processing will export SVG, and has many features to make it easy to draw things. It is a very heavy dependency for my purposes, but it is a good tool for many people.

3 Tools That Do Not Automate Enough

3.1 Asymptote


Asymptote is a powerful descriptive vector graphics language that provides a natural coordinate-based framework for technical drawing. Labels and equations are typeset with LaTeX, for high-quality PostScript output.

Might be good; haven’t used it. Has a jupyter extension

3.2 PlotDevice

PlotDevice is a cousin of nodebox, which is to say, a python drawing system 2d vector printable outputs.

4 Tools That Automate Too Much

4.1 Kroki

Not so much a vector graphics engine as generic renderer for many vector graphics engines. See Kroki!. It is much ore generic that merely javascript, and in fact supports a many tools with different languages and backends. It is open-source, and can be installed as a local web server or command-line. Has many integrations, e.g. Kroki Filter for pandoc.

4.2 D2

Looks pretty cool. Which means I won’t use it because getting distracted by cool things is a known failure mode of mine. Also it only does layout via fancy algorithms that do not do what I want.

Create beautiful diagrams in minutes. Simple syntax. Endlessly customizable. D2 is the fastest and easiest way to get a mental model from your head onto the screen, then make edits with your team.

D2 Documentation

4.3 PlantUML

Open-source tool that uses simple textual descriptions to draw UML diagrams..

4.4 Mermaid

Another browser option mermaid is a flowcharting tool. Unique Value Proposition: code-driven diagrams with a syntax that aspires to be so basic that it is easier than point and click. Integrates with many markdown editors. Has an online editor, and a CLI.

It has yet to solve a problem for me however.

4.5 Graphviz

The graphviz family is nearly good, in that it supports graphing various networks, including probabilistic DAGs. Inevitably, none of its fancy algorithms ever lay it out quite like I want. There is a macOS gui and a cross-platform (WX) gui called doteditor.

Figure 2: graphviz model with the fastdot theme

5 Probabilistic graphical models

See diagramming graphical models.

6 via javascript

A popular option. So popular that it does not even fit in here. See javascript vector graphics.