Procedurally generated diagrams
Of the kind I need, a practical guide to the creation thereof
March 2, 2015 — February 29, 2024
diagrams generated via text rather than point-and-click.
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
I want layout to be easy and yet to have some control over how it works. Tools that give me the ability to lay out nodes with relative positioning and not too much book-keeping are the ones that I find most useful. Here are some of those.
1.1 TikZ/pstricks/PGFplots
The classic type-your-diagram-in-then-work-out-what-went-wrong option.
I use this a lot these days, including on this blog, and I accordingly made it a new notebook of its own.
1.2 Cetz
Cetz reimagines Tikz for LatTeX competitor, Typst. Have not tried it, but it looks aesthetic.
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.
1.4 Processing
Processing.org 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 when you need it.
Major weakness: decades of badly maintained community libraries make it unclear what it actually current.
2 Tools That Do Not Automate Enough
If I have a flexible tool but I need to keep a calculator next to my computer to constantly re-adjust the mathematics every time I move something, then it does not automate enough. Any tool which is based on absolute canvas coordinates rather than “connect this to this”, “wrap this around that” is not going to be useful to me.
2.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
2.2 PlotDevice
PlotDevice is a cousin of nodebox, which is to say, a python drawing system 2d vector printable outputs.
3 Tools That Automate Too Much
Tools that have obligatory fancy layout engines sound great. However, after trying them all, none of them have been very helpful to me, because I inevitably find myself having not quite the layout I want and no scope to change it.
3.1 Kroki
Not so much a vector graphics engine as generic renderer for many vector graphics engines. See Kroki!. It 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.
Unfortunately, none of the languages that it supports are the ones I want to use.
3.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.
3.3 PlantUML
Open-source tool that uses simple textual descriptions to draw UML diagrams..
3.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.
3.5 Graphviz
The graphviz family is nearly good, in that it supports graphing various networks, including probabilistic DAGs. Once again, all of its layout engines sound cook as exercises in layout engine design, but do not help me in practice.
There is a macOS gui and a cross-platform (WX) gui called doteditor.
fastdot theme
4 For probabilistic graphical models
5 via javascript
A popular option. So popular that it does not even fit in here, and there is a whole special subsection on details. See javascript vector graphics.