HowtoDirectedGraphs < TWiki

---+!! Overview of directed graph editing

| %X% *Caution* =&lt;dot&gt;= syntax is not compatible with versions of TWiki:Extensions.WysiwygPlugin prior to 28 June 2009. It is recommended that you upgrade !WysiwygPlugin if you are running an older version. If that is not practical then raw editing is recommended, or use &lt;sticky&gt; tags to protect the dot tags. |

<!-- NOTE:  The dot graphs on this page are all configured with file hash disabled.  
If you want to modify any of them remove the dothash parameter from the dot directive
Attachments are shipped with this topic - must use API to access them.
   * Set FORCEATTACHAPI="yes"
-->

%TOC%

---++ Introduction

Support for creating advanced directed graphs has been installed on this TWiki installation. Directed graphs are rendered by [[http://www.graphviz.org][Graphviz]]. Only the most important basics are covered here, you should consult the dotguide.pdf from Graphviz's homepage for a more thorough guide on creating directed graphs.

---++ What are directed graphs?

<table>
<tr><td valign="top">
*The graph:*

<dot file="example1"  dothash="off" >
digraph G {
  "a" -> "b";
  "a" -> "c";
  {
    rank = same;
    "b";
    "c";
  }
}
</dot>

</td><td valign="top">
To the left here you can see a simple directed graph with three ="nodes"=, one on the top and two below (which are connected from top to bottom). Connecting these nodes you can also see two ="edges"=, which is the technical term for the arrow connecting the three nodes.

When entering directed graphs in TWiki, everything you do is to define nodes and their edges (or connections); the directed graph engine then does all placing by itself, fully automatic.

No layout more than which nodes and their relationship, together with node and edge style is defined by the author; the engine takes care of *all* layout and placing of nodes, which makes creating advanced graphs extremely simple and fast.

Using more advanced syntax very advanced graphs can be created, including subgraphs and balanced trees and record graphs. This document only focusses on "normal" directed graphs; if you want to experiment more with the graph engine, consult the dotguide on www.graphviz.org.
</td>
</tr>
</table>

---++ Examples

---+++ A simple graph with two nodes

<table>
<tr><td valign="top">
*The graph:*

<dot file="simple_two_nodes" dothash="off" >
digraph G {
 a -> b;
}
</dot>
</td>
<td valign="top">
*The code:*

<verbatim>
<dot file="simple_two_nodes" dothash="off">
digraph G {
 a -> b;
}
</dot>
</verbatim>
</td><td valign="top">
*Explanation:*

In order to describe a graph you start by typing:
<verbatim>
<dot>
digraph G {
</verbatim>
After the curly opening bracket (={=) the actual graph description is located. When you have defined your graph you close it by typing:
<verbatim>
}
</dot>
</verbatim>

Inside those two parts you place your graph description. You can define nodes and edges (connection between nodes); you define edges by typing =="node1" -> "node2";== which also implicit defines both nodes =node1= and =node2=. If the nodes' names doesn't contain spaces or other special characters, the quotation marks can be ignored.

As you can see in this example we actually only define exactly one edge, the link between node =a= and node =b=, by typing ==a -> b;==. Note also how the line is terminated by a semi-colon (=;=).
</td>
</tr>
</table>

---+++ Added attributes to nodes and edges

<table>
<tr><td valign="top">
*The graph:*

<dot file="added_attributes" dothash="off">
digraph G {
 a [style=filled, color=green];
 b [style=filled, color=red];

 a -> b [style=dotted, color=blue];
}
</dot>
</td>
<td valign="top">
*The code:*

<verbatim>
<dot file="added_attributes" dothash="off">
digraph G {
 a [style=filled, color=green];
 b [style=filled, color=red];

 a -> b [style=dotted, color=blue];
}
</dot>
</verbatim>
</td><td valign="top">
*Explanation:*

This example is very similar to the above example, with the difference that we have defined some attributes to both the nodes and the edge. As you can see the nodes are filled with green and red, respective. The edge has been changed to have a dotted line instead of a solid line.

If you want to assign attributes to nodes, the nodes have to be defined first, which means they appear on a line on their own. The order of node and edge definitions is not important, the whole file is parsed before any layout is begun.

The first line in the graph ==a [style=filled, color=green];== defines the node =a= and assigns the attributes =style=filled= and =color=green=. These two attributes make the node filled with the color green.
</td>
</tr>
</table>

As you can see to assign attributes to a node you just type its name (with the optional quotation marks) followed by the attribute definitions separated by commas, as it appears in the example above.

To add attributes to edges (i.e. arrows) just add the attributes to the line of the edge definition as can be seen on the last line of the graph definition.

---+++ Adding labels to edges

<table>
<tr><td valign="top">
*The graph:*

<dot file="with_labels" dothash="off">
digraph G {
 a -> b [label="link"];
}
</dot>
</td>
<td valign="top">
*The code:*

<verbatim>
<dot file="with_labels" dothash="off">
digraph G {
 a -> b [label="link"];
}
</dot>
</verbatim>
</td><td valign="top">
*Explanation:*

Edges can be labelled by adding the attribute ==label="text"== at the edge definition, as can be seen in the code of this example.
</td>
</tr>
</table>

---+++ Adding subgraphs

<table>
<tr><td valign="top" >
*The graph:*

<dot file="add_subgraphs" dothash="off" >
digraph G {
  a -> b;
  a -> c;

  subgraph cluster0 {
    style=filled;
    color=lightgrey;
    rank=same;

    node [style=filled, color=white];
    b;
    c;
  }

  c -> d;
  b -> d;
}
</dot>
</td>
<td valign="top">
*The code:*

<verbatim>
<dot file="add_subgraphs" dothash="off" >
digraph G {
  a -> b;
  a -> c;

  subgraph cluster0 {
    node [style=filled, color=white];
    style=filled;
    color=lightgrey;
    rank=same;
    b;
    c;
  }

  c -> d;
  b -> d;
}
</dot>
</verbatim>
</td><td valign="top">
*Explanation:*

If you want to group nodes together, you put the node definitions inside a ==subgraph clusterXXX { }== statement.

*Note:* the name of the subgraph *must* begin with ==cluster==.

The subgraph has the attributes ==style=filled== and ==color=lightgrey== which makes the subgraph filled with the color light grey. The subgraph also has the attribute ==rank=same== which makes all nodes defined inside the subgraph appear on the same level (i.e. they have the same rank).

You can also see the nodes =b= and =c= are defined in the subgraph by the last two lines in the subgraph.

All nodes defined in the subgraph have the attributes =style=filled, color=white= by adding the line ==node [style=filled, color=white];==.
</td>
</tr>
</table>

---+++ Grouping nodes

<table>
<tr><td valign="top">
*The graph:*

<dot file="grouping_nodes" dothash="off" >
digraph G {
  size="2.5,2";

  {
    node [shape=plaintext, fontsize=16];

    1975 -> 1980 -> 1985;
  }

  { rank=same; 1975; a; b; c; }
  { rank=same; 1980; d; e; }
  { rank=same; 1985; f; g; h; i; }

  a -> d;
  b -> e;
  c -> e;
  d -> f;
  e -> g;
  e -> h;
  e -> i;
}
</dot>
</td>
<td valign="top">
*The code:*

<verbatim>
<dot file="grouping_nodes" dothash="off" >

digraph G {
  {
    node [shape=plaintext, fontsize=16];

    1975 -> 1980 -> 1985;
  }

  { rank=same; 1975; a; b; c; }
  { rank=same; 1980; d; e; }
  { rank=same; 1985; f; g; h; i; }

  a -> d;
  b -> e;
  c -> e;
  d -> f;
  e -> g;
  e -> h;
  e -> i;
}
</dot>
</verbatim>
</td><td valign="top">
*Explanation:*

In this graph three groups are defined, by putting them inside a block, defined by ={ }=.

The first group defines the nodes =1975=, =1980= and =1985=, by connecting them together; these nodes are of the type ="plaintext"= with font size equal to 16. We do this because the years are to be placed to the left as a timeline and therefore the font size is choosen to be a little larger.

The next three groups for example =={ rank=same; 1975; a; b; }== ensures that the nodes =1975=, =a= and =b= are on the same level, of course, because =a= and =b= occured in 1975 (_It is left as an exercise to the reader to figure out what a and b actually is_).

Following the last group definition we define all edges.
</td>
</tr>
</table>

---+++ Ladder Diagrams

<table>
<tr><td valign="top">
*The graph:*

<dot map="1" file="ladder_diagram" dothash="off">
digraph ladder {  ranksep=".1"; nodesep=".1"; size="3,3.5"; 

# Define the defaults
  node [shape=point fontsize=10]
  edge [dir=none fontsize=10]

# Define the top nodes
  left [shape=none]
  right [shape=none]

# Column labels
  a [shape=none]
  b [shape=none]
  c [shape=none]
  d [shape=none]

# Leftmost vertical column
  left -> a [style=invis]  a -> a1 [style=invis] 
  a1 -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 ->
    a11 -> a12 -> a13 [weight=1000]

# Rightmost vertical column
  right -> d [style=invis]   d -> d1 [style = invis]
  d1 -> d2 -> d3 -> d4 -> d5 -> d6 -> d7 -> d8 -> d9 -> d10 ->
    d11 -> d12 -> d13 [weight=1000]

# Draw the top labels with the dotted line
  { rank=same; left right
    left -> right [style=dotted]  }

# Draw the 4 column headings, no line
  { rank=same; 
    edge[style=invis]
    a -> b -> c -> d   }

# Draw the two center columns
  b1 -> b2 -> b3 -> b4 -> b5 -> b6 -> b7 -> b8 -> b9 -> b10
  c1 -> c2 -> c3 -> c4 -> c5 -> c6 -> c7 -> c8 -> c9 -> c10
  
# Now each step in the ladder
  { rank=same; 
    a2 -> b2 [dir=forward label="S1" URL="http://twiki.org/" ]  }
  { rank=same; 
    b3 -> c3 [dir=forward label="S2" URL="#EndNote" ]  }
  { rank=same; 
    c4 -> d4 [dir=forward label="A"]  }
  { rank=same; 
    c5 -> d5 [dir=back label="B"]  }
  { rank=same; 
    b6 -> c6 [dir=back label="C"]  }
  { rank=same; 
    a7 -> b7 [dir=back label="D"]  }
  { rank=same; 
    a8 -> b8 [dir=forward label="E"]  }
  { rank=same; 
    a9 -> b9 [dir=back label="F"]
    b9 -> c9 [dir=forward label="G"]  }
  { rank=same; 
    a10 -> b10 [dir=back label="H"]  }
  { rank=same; 
    a11 -> d11 [dir=forward label="I"]  }
  { rank=same; 
    a12 -> d12 [style=dashed dir=both label="J"]  }
}
</dot>
</td>
<td valign="top">
*The code:*

<verbatim>
<dot map=1>
digraph ladder {  ranksep=".1"; nodesep=".1"; 

# Define the defaults
  node [shape=point fontsize=10]
  edge [dir=none fontsize=10]

# Define the top nodes
  left [shape=none]
  right [shape=none]

# Column labels
  a [shape=none]
  b [shape=none]
  c [shape=none]
  d [shape=none]

# Leftmost vertical column
  left -> a [style=invis]  a -> a1 [style=invis] 
  a1 -> a2 -> a3 -> a4 -> a5 -> a6 -> a7 -> a8 -> a9 -> a10 ->
    a11 -> a12 -> a13 [weight=1000]

# Rightmost vertical column
  right -> d [style=invis]   d -> d1 [style = invis]
  d1 -> d2 -> d3 -> d4 -> d5 -> d6 -> d7 -> d8 -> d9 -> d10 ->
    d11 -> d12 -> d13 [weight=1000]

# Draw the top labels with the dotted line
  { rank=same; left right
    left -> right [style=dotted]  }

# Draw the 4 column headings, no line
  { rank=same; 
    edge[style=invis]
    a -> b -> c -> d   }

# Draw the two center columns
  b1 -> b2 -> b3 -> b4 -> b5 -> b6 -> b7 -> b8 -> b9 -> b10
  c1 -> c2 -> c3 -> c4 -> c5 -> c6 -> c7 -> c8 -> c9 -> c10
  
# Now each step in the ladder
  { rank=same; 
    a2 -> b2 [dir=forward label="S1" URL="http://twiki.org/" ]  }
  { rank=same; 
    b3 -> c3 [dir=forward label="S2" ]  }
  { rank=same; 
    c4 -> d4 [dir=forward label="A"]  }
  { rank=same; 
    c5 -> d5 [dir=back label="B"]  }
  { rank=same; 
    b6 -> c6 [dir=back label="C"]  }
  { rank=same; 
    a7 -> b7 [dir=back label="D"]  }
  { rank=same; 
    a8 -> b8 [dir=forward label="E"]  }
  { rank=same; 
    a9 -> b9 [dir=back label="F"]
    b9 -> c9 [dir=forward label="G"]  }
  { rank=same; 
    a10 -> b10 [dir=back label="H"]  }
  { rank=same; 
    a11 -> d11 [dir=forward label="I"]  }
  { rank=same; 
    a12 -> d12 [style=dashed dir=both label="J"]  }
}
</dot>
</verbatim>
<td valign=top>
*Explanation:*
The ladder diagram uses the =weight= operand to force straight edges.  The heaver the weight, the edge will be shorter, straighter, and closer to vertical. 

Defaults are established using =dir=none= for the edges.  This causes the edge lines to be undirected, and are drawn without an arrow.

The edges of the top two rows specify =style=invisible=. This keeps the columns aligned, but omits drawing any lines.

Each horizontal "rung" in the ladder is kept on the same level by specifying =rank=same=
</td>
</tr>
</table>
---+++ Node types

Choose the shape of a node by adding the attribute =shape= to the node definition.

<table border="1"><tr>
<td>
<dot file="shape_box" dothash="off" >
digraph G {
 " " [shape=box];
}
</dot>
<center>box</center>
</td>
<td>
<dot file="shape_polygon" dothash="off" >
digraph G {
 " " [shape=polygon];
}
</dot>
<center>polygon</center>
</td>
<td>
<dot file="shape_ellipse" dothash="off" >
digraph G {
 " " [shape=ellipse];
}
</dot>
<center>ellipse</center>
</td>
<td>
<dot file="shape_circle" dothash="off" >
digraph G {
 " " [shape=circle];
}
</dot>
<center>circle</center>
</td>
</tr><tr>
<td>
<center>
<dot file="shape_point" dothash="off" >
digraph G {
 " " [shape=point];
}
</dot>
</center>
<center>point</center>
</td>
<td>
<dot file="shape_egg" dothash="off" >
digraph G {
 " " [shape=egg];
}
</dot>
<center>egg</center>
</td>
<td>
<dot file="shape_triangle" dothash="off" >
digraph G {
 " " [shape=triangle];
}
</dot>
<center>triangle</center>
</td>
<td>
<dot file="shape_plaintext" dothash="off" >
digraph G {
 plaintext [shape=plaintext];
}
</dot>
<center>plaintext</center>
</td>
<tr>
<td>
<dot file="shape_diamond" dothash="off" >
digraph G {
 " " [shape=diamond];
}
</dot>
<center>diamond</center>
</td>
<td>
<dot file="shape_trapezium" dothash="off" >
digraph G {
 " " [shape=trapezium];
}
</dot>
<center>trapezium</center>
</td>
<td>
<dot file="shape_parallelogram" dothash="off" >
digraph G {
 " " [shape=parallelogram];
}
</dot>
<center>parallelogram</center>
</td>
<td>
<dot file="shape_house" dothash="off" >
digraph G {
 " " [shape=house];
}
</dot>
<center>house</center>
</td>
</tr><tr>
<td>
<dot file="shape_hexagon" dothash="off" >
digraph G {
 " " [shape=hexagon];
}
</dot>
<center>hexagon</center>
</td>
<td>
<dot file="shape_octagon" dothash="off" >
digraph G {
 " " [shape=octagon];
}
</dot>
<center>octagon</center>
</td>
<td>
<dot file="shape_doublecircle" dothash="off" >
digraph G {
 " " [shape=doublecircle];
}
</dot>
<center>doublecircle</center>
</td>
<td>
<dot file="shape_doubleoctagon" dothash="off" >
digraph G {
 " " [shape=doubleoctagon];
}
</dot>
<center>doubleoctagon</center>
</td>
</tr>
<tr>
<td>
<dot file="shape_tripleoctagon" dothash="off" >
digraph G {
 " " [shape=tripleoctagon];
}
</dot>
<center>tripleoctagon</center>
</td>
<td>
<dot file="shape_invtriangle" dothash="off" >
digraph G {
 " " [shape=invtriangle];
}
</dot>
<center>invtriangle</center>
</td>
<td>
<dot file="shape_invtrapezium" dothash="off" >
digraph G {
 " " [shape=invtrapezium];
}
</dot>
<center>invtrapezium</center>
</td>
<td>
<dot file="shape_invhouse" dothash="off" >
digraph G {
 " " [shape=invhouse];
}
</dot>
<center>invhouse</center>
</td>
</tr><tr>
<td>
<dot file="shape_Mdiamond" dothash="off" >
digraph G {
 " " [shape=Mdiamond];
}
</dot>
<center>Mdiamond</center>
</td>
<td>
<dot file="shape_Msquare" dothash="off" >
digraph G {
 " " [shape=Msquare];
}
</dot>
<center>Msquare</center>
</td>
<td>
<dot file="shape_Mcircle" dothash="off" >
digraph G {
 " " [shape=Mcircle];
}
</dot>
<center>Mcircle</center>
</td>
</tr></table>

---+++ Arrow types

The form of the edge can be set by using the =arrowtail= and =arrowhead= attributes with edges. The attribute ==arrowtail== sets the shape of the arrow at the source node, while ==arrowhead== sets the shape of the arrow at the destination node.

<table border="1">
<tr>
<td>
<dot file="arrow_normal" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=normal];
}
</dot>
<center>normal</center>
</td>
<td>
<dot file="arrow_dot" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=dot];
}
</dot>
<center>dot</center>
</td>
<td>
<dot file="arrow_odot" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=odot];
}
</dot>
<center>odot</center>
</td>
<td>
<dot file="arrow_inv" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=inv];
}
</dot>
<center>inv</center>
</td>
</tr><tr>
<td>
<dot file="arrow_invdot" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=invdot];
}
</dot>
<center>invdot</center>
</td>
<td>
<dot file="arrow_invodot" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=invodot];
}
</dot>
<center>invodot</center>
</td>
<td>
<dot file="arrow_none" dothash="off" >
digraph G {
  a [shape=point];

  a -> " " [arrowhead=none];
}
</dot>
<center>none</center>
</td>
</tr></table>

-- TWiki:Main.MikaelOlenfalk - 08 Aug 2005

Attachments

Topic attachments
I	Attachment	History	Action	Size	Date	Who	Comment
png	add_subgraphs.png	r1	manage	11.4 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	added_attributes.png	r1	manage	3.2 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_dot.png	r1	manage	2.6 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_inv.png	r1	manage	2.6 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_invdot.png	r1	manage	2.9 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_invodot.png	r1	manage	2.9 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_none.png	r1	manage	2.4 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_normal.png	r1	manage	2.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	arrow_odot.png	r1	manage	2.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	example1.png	r1	manage	6.9 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	grouping_nodes.png	r1	manage	10.5 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
cmapx	ladder_diagram.cmapx	r1	manage	0.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	ladder_diagram.png	r1	manage	7.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_Mcircle.png	r1	manage	1.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_Mdiamond.png	r1	manage	1.8 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_Msquare.png	r1	manage	0.6 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_box.png	r1	manage	0.3 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_circle.png	r1	manage	1.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_diamond.png	r1	manage	1.3 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_doublecircle.png	r1	manage	3.4 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_doubleoctagon.png	r1	manage	1.2 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_egg.png	r1	manage	2.2 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_ellipse.png	r1	manage	2.1 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_hexagon.png	r1	manage	1.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_house.png	r1	manage	1.2 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_invhouse.png	r1	manage	1.3 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_invtrapezium.png	r1	manage	1.4 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_invtriangle.png	r1	manage	2.1 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_octagon.png	r1	manage	0.7 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_parallelogram.png	r1	manage	1.4 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_plaintext.png	r1	manage	1.3 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_point.png	r1	manage	0.2 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_polygon.png	r1	manage	0.3 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_trapezium.png	r1	manage	1.5 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_triangle.png	r1	manage	1.8 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	shape_tripleoctagon.png	r1	manage	1.6 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	simple_two_nodes.png	r1	manage	3.2 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script
png	with_labels.png	r1	manage	4.6 K	2020-04-26 - 03:41	TWikiAdminUser	Saved by install script

This topic: TWiki > Plugins > DirectedGraphPlugin > HowtoDirectedGraphs
Topic revision: r3 - 2024-03-02 - TWikiAdminUser

Copyright © 1999-2025 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.HowtoDirectedGraphs.