Procedurally generated diagrams
Of the kind I need, a practical guide to the creation thereof
2015-03-02 — 2025-06-10
Wherein diagrams are produced by text rather than point-and-click, and a survey is presented of tools from automated to manual layout, with emphasis on relative positioning over absolute coordinates
We generated diagrams via text rather than point-and-click.
Python, R, Julia, JavaScript, among others, They all have diverse plotting infrastructure, some of which doubles as diagramming infrastructure. In practice, I often generate part of a diagram this way, but rarely the whole thing.
The major distinction among these tools is whether they automate layout entirely and remove control, or they don’t help with layout at all and demand heinous manual work. Tools in the middle — those that make layout easy but not automatic — are the ones that help me most in practice.
1 Tools That Automate Just Enough But Have Other Difficulties
I want layout to be easy but still let me control how it works. Tools that let me lay out nodes using relative positioning without too much bookkeeping are the 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, so I made a new notebook of its own.
1.1.1 CeTZ
CeTZ reimagines TikZ for the LaTeX competitor Typst. I haven’t tried it, but it looks aesthetic.
1.2 Penrose
It comes recommended by friends, but I haven’t tried it myself. It looks very elegant. Distractingly elegant. Suspiciously elegant. It handles implicit declarative diagrams, uses many constraint-satisfaction tricks, offers attractive graphical styles and produces lovely outputs. Is it designed to distract me?
Penrose is a platform that enables people to create beautiful diagrams just by typing notation in plain text.
Our goal is to make it easy for non-experts to create high-quality diagrams and provide deeper insight into challenging technical concepts.
We aim to democratize the process of creating visual intuition.
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 is actually current.
1.5 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.
It might be good; I haven’t used it. It has a Jupyter extension that hasn’t been touched since 2012. The gallery shows the flavour of what it can do.
2 Tools That Do Not Automate Enough
If I have a flexible tool but need to keep a calculator next to my computer to constantly readjust the mathematics every time I move something, it doesn’t automate enough. Any tool which is based on absolute canvas coordinates rather than “connect this to this”, “wrap this around that” won’t be useful to me.
2.1 PlotDevice
PlotDevice is a cousin of NodeBox, which is to say, a Python drawing system for 2D vector print-ready output. It has a macOS-only GUI, which isn’t ideal for my purposes.
3 Tools That Automate Too Much
Tools with obligatory fancy layout engines sound great. However, after trying them all, none have been very helpful to me, because I inevitably find I don’t quite have the layout I want and there’s no scope to change it.
3.1 Kroki
It’s not so much a vector graphics engine as a generic renderer for many vector graphics engines. See Kroki!. It supports many tools with different languages and backends. It’s open-source, and can be installed as a local web server or run from the command line. It has many integrations, e.g. Kroki Filter for pandoc.
Unfortunately, none of the languages it supports are ones I want to use.
3.2 D2
It looks pretty cool. That 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 don’t 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 aims to be so basic it’s easier than point-and-click. It integrates with many Markdown editors. It has an online editor, and a CLI.
However, it hasn’t solved a problem for me.
3.5 Graphviz
The Graphviz family is almost good, in that it supports graphing various networks, including probabilistic DAGs. Once again, all of its layout engines sound cool as exercises in layout-engine design, but they don’t 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
It’s a popular option — so popular it doesn’t even fit here, and there’s a whole subsection with the details. See JavaScript vector graphics.