|||
This is a quick summary. There are more details and examples here.
Every line is either blank or defines a variable or a box.
Just type characters:
my variableYou can use dots at the beginning of a line to define a link from a to b:
a
.b
You can use spaces at the beginning of a line to define a link from b to a:
a
b
You can use a decimal notation common in logframes etc:
a
a.1
a.1.x
a.2
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
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=aYou 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.
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=cBoxes 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 boxBoxes 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=orangeYou 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.
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.