The grammar of Theory Maker

This is a quick summary. There are more details and examples here.

Every line is either blank or defines a variable or a box.

Define a variable

Just type characters:

my variable

Defining edges between variables


You can use dots at the beginning of a line to define a link from a to b:




You can use spaces at the beginning of a line to define a link from b to a:




You can use a decimal notation common in logframes etc:






Or, most generally, you can use this to= notation to construct an edge to another node:

a; to=b

You can give more than one target by listing more than one variable, separated by spaces. Note that case is important, so to=A is not the same as to=a

a; to=b c

So the names of the targets have to be without spaces:

my variable another variable; to=myvariable

Using aliases

If you are using to= and you have have long variable labels it can be tedious to have to retype them. So you can give the target variable a simpler alias by adding characters before a colon. The second part is shown as the label, but the first (simpler) part can be used to refer to the variable elsewhere

a::my variable
b; to=a

Allowed characters

You can use ( ) ! ? . , in the names of your variables. Don’t use " = + ; or '. If you are using to=, remove anything except letters and numbers from the name of the target.

Implied variables

If you imply a variable using the to= or decimal methods without actually defining it, like c in the example below, the variable will be shown in grey.

b; to=c


Boxes are used to group variables. A box is introduced by a box definition: a line starting with one or more dashes: -. What comes after will be printed as the label of the box. Boxes with more dashes will be printed a bit smaller.

--My big box

Boxes with more dashes are shown inside boxes with fewer dashes.

You can finish off” one box without starting another by typing a line with the same number of dashes but no text.

Variables following a box definition are shown inside the box. (If a variable appears more than once in the text, the last appearance determines which box it will be shown in.)

The edges between variables are not affected by boxes, though the layout may change a little.

That is it. The rest is decoration.


Variables, edges, boxes and indeed the diagram itself can be decorated by adding little phrases of the form attribute=value, separated by semicolons, like this:

my variable; fillcolor=orange

You can find out more about decoration here.


The diagrams are intended to represent causal networks, i.e. a set of causal connections between variables. So if one or more variables point to another, they are to be understood as influencing the variable at the receiving end of the arrows. It is possible to make cyclic diagrams, in which you can trace a path from a variable down the arrows back to the same variable. We usually think of these as feedback loops”. The interpretation of cyclic diagrams is not quite so easy, which is one reason why they are traditionally discouraged in project modelling; usually we have to think of the variables as representing the same thing at different times.

The basic premise is that it causal networks are a good way to model projects and programmes. This is great because there is a big and growing literature about causal networks, so if and when we need to think more formally about projects and issues like adaptability, chaos, complexity, contribution and attribution, we can base it on this powerful new science. This is what I am attempting to do in my forthcoming book.

Interpretation of boxes

The whole point about boxes is that we don’t really interpret them. They are for when you want to group variables in some way - phase 1, phase 2, variables concerning children, variables concerning parents, inputs, outputs, etc, without any causal interpretation.

One of the big problems with logical frameworks etc is that they don’t have boxes: they don’t have a way of grouping or organising variables which do not imply a causal connection. So we end up having to create, for example, pseudo goal” variables as a way of grouping or listing or organising outcomes even when the goal” is not really a causally separate variable and the outcomes do not really causally influence it.

Unlike with other, purer ways to draw graphs like plantUML and Graphviz itself, the edges between variables do not get their own lines. Instead, you define them when you define your variables. For convenience, there are four different ways to do this, which are all basically the same.


A Theory Maker diagram consists firstly of variables, which may be linked to one another with directed edges, i.e. lines which usually have arrowheads. So formally, a diagram is a directed graph. Secondly, there are boxes, which may contain variables and which may be nested inside one another. A diagram may contain variables (and maybe edges) and/or boxes.

Variables, edges and boxes may also be decorated in various ways, for example edges may have labels and variables may have special colours. Also the whole diagram may have a title and possibly a legend.

Up next Theory Maker and markdown Theory Maker is a free and simple web app for making diagrams of theories of change etc. I already wrote about it. Its special feature is that you The theory behind theories of change This essay will look at the theory behind theories of change. First of all it is a quick introduction to my forthcoming book provisionally entitled
Latest posts Causal Mapping - an earlier guide The walk to school in Sarajevo Glitches Draft blog post for AEA365 Theory Maker! Inventory & analysis of small conservation grants, C&W Africa - Powell & Mesbach! Lots of charts! Answering the “why” question: piecing together multiple pieces of causal information rbind.fill for 1-dimensional tables in r yED graph editor Examples of trivial graph format Using attr labels for ggplot An evaluation puzzle: “Talent show” An evaluation puzzle: “Mobile first” An evaluation puzzle: “Many hands” An evaluation puzzle: Loaves and fishes An evaluation puzzle: “Freak weather” An evaluation puzzle: “Billionaire” Publications Using Dropbox for syncing Shiny app data on Amazon EC2 Progress on the Causal Map app Articles and presentations related to Causal Maps and Theorymaker Better ways to present country-level data on a world map: equal-area cartograms A starter kit for reproducible research with R A reproducible workflow for evaluation reports Welcome to the Wiggle Room Realtime comments on a Theory of Change Responses to open questions shown as tooltips in a chart A panel on visualising Theories of Change for EES 2018? Peer mentoring for evaluators How do you explain reproducible research to clients? Links for my AEA eval2017 presentation, Washington DC