Hide
Free your code from a slow death on your hard drive Join Siafoo Now or Learn More

Flow Graphs Atom Feed 0

1   About Graphs

You can easily create and embed graphs in Siafoo's reStructured Text, as well as use them independently in a few places. We use some magic [1] to generate the images using Graph::Easy, an awesome Perl module.

In case you are wondering, a graph looks like this:

If you're looking for the other kind of graph, see Charts.

You can follow along using the Siafoo reST demo if you'd like.

Note

Graphs that are not embedded inside articles, snipets, etc. are pruned from the database a couple of times a week. If you want a rendered graph image to stick around, stick it in something.

2   Embedding

To embed a graph in reST, you need to use the .. graph:: directive. Pass the graph information as content: indented and separated with blank lines. For the graph information, you get a choice of formats; we'll explain those next.

3   Supported Formats

Siafoo understands the following graph languages:

All three languages allow for the definition of nodes and the edges that connect them. Properties, like as shape, size, color, and labels, can also be set per graph, node, and edge. The languages differ in their syntax and the amount of properties they allow for each element but the rendering engine is the same for all three, meaning the end results will look similar.

When choosing a language, consider the complexity of the graph you are trying to create. For simpler graphs, Graph::Easy is the way to go, its syntax is clear and easy to understand. If you need more esoteric attributes in your graphs, or require their code to be highly portable, take the time to learn the Graphviz language.

3.1   Graph::Easy

Although Graph::Easy is the simplest and easiest-to-use format we support, it will still allow you to create highly complex graphs with many nodes and interconnected edges. The properties of the nodes and edges can be customized using dozens of attributes.

The Graph::Easy manual is an excellent starting point for learning how to create a graph.

The color, shape, and orientation of the nodes and edges can be customized to your liking. See the attributes reference for more information.

All the supported color values can be found at the color reference page.

For example:

.. graph::

    node.hdr { color: red; }
    node.src { fill: lightgreen; }
    node.stage { fill: lightblue; }

    (Libraries: [Library 1]{ shape: diamond;},
                [Library 2]{ shape: diamond;},
                [Library 3]{ shape: diamond;})

    [Header 1]{class: hdr;},
    [Header 2]{class: hdr;},
    [Header N]{class: hdr;}-> [Preprocessor]{shape:circle; class:stage;} -> [Intermediate 2],
                                                                          [Intermediate 1] ->[Compiler]
    [Source 1]{class: src;}, [Source 2]{class: src;}-> [Preprocessor]

    [ Compiler ]{shape:circle; class:stage;} -> [ Object 2], [ Object 1] -> [ Linker ]

    [Library 1], [Library 2], [Library 3] -> [Linker]{shape:circle; class:stage;}
    [Linker] -> [Binary2]

This code will generate:

As you can see, relatively simple code can create a complex graph.

3.2   Graphviz

Graphviz format is more complicated to use than Graph:Easy but also more powerful. It supports more shapes and attributes and allows for finer control over the size and placement of the nodes.

To signal the graph processor that you are going to create a Graphviz graph, wrap the graph code in a digraph foo { ... } as shown below. Note that the 'foo' doesn't matter, use whatever word you want. : )

For information on creating graphs with Graphviz see the Graphviz documentation.

A simple example:

.. graph::

    digraph foo {
        rankdir=LR;
        size="2.5,2.5"
        node [shape = circle];

        A [fillcolor = cornflowerblue];
        B [fillcolor = red];
        C [fillcolor = gold];
        A -> C [ label = "A-C" color = cornflowerblue];
        A -> B [ label = "A-B" color = red];
        A -> A [ label = "WTF?"];
        C -> B;

    }

You've already seen this one; the code produces:

Here's another example, a finite state machine from the Graphviz website:

.. graph::

    digraph finite_state_machine {
        rankdir=LR;
        size="8,5"
        node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
        node [shape = circle];
        LR_0 -> LR_2 [ label = "SS(B)" ];
        LR_0 -> LR_1 [ label = "SS(S)" ];
        LR_1 -> LR_3 [ label = "S($end)" ];
        LR_2 -> LR_6 [ label = "SS(b)" ];
        LR_2 -> LR_5 [ label = "SS(a)" ];
        LR_2 -> LR_4 [ label = "S(A)" ];
        LR_5 -> LR_7 [ label = "S(b)" ];
        LR_5 -> LR_5 [ label = "S(a)" ];
        LR_6 -> LR_6 [ label = "S(b)" ];
        LR_6 -> LR_5 [ label = "S(a)" ];
        LR_7 -> LR_8 [ label = "S(b)" ];
        LR_7 -> LR_5 [ label = "S(a)" ];
        LR_8 -> LR_6 [ label = "S(b)" ];
        LR_8 -> LR_5 [ label = "S(a)" ];
    }

This code produces:

3.3   VCG

The 'Visualization of Compiler Graphs' format is also supported by Siafoo. You tell the grapher you are going to create a VCG graph by wrappnig it in graph: {...}, as shown below.

For more information on this format and its syntax, see the VCG homepage

Here is an example graph from the VCG website:

.. graph::

    graph: { title: "SYNTAXTREE"
         height: 700
         width: 700
         x: 30
         y: 30
         stretch: 7
             shrink: 10
             layout_downfactor: 10
             layout_upfactor:   1
             layout_nearfactor: 0
         manhattan_edges: yes
             node: {title:"A"
            label:"Struct bar\n\f22next\n\f29content" }
             node: {title:"B"
            label:"Struct bar\n\f22next\n\f29content" }
             node: {title:"C"
            label:"Struct bar\n\f22next\n\f29content" }
             node: {title:"D"
            label:"Struct bar\n\f22next\n\f29content" }
         edge: { color: lilac sourcename:"A" targetname:"B" anchor: 2 }
         edge: { color: lilac sourcename:"B" targetname:"C" anchor: 2 }
         edge: { color: lilac sourcename:"C" targetname:"D" anchor: 2 }

             node: {title:"AS"
            label:"Struct foo\n\f01field A\n\f02field B\n\f11field C"  }
             node: {title:"BS"
            label:"Struct foo\n\f01field A\n\f02field B\n\f11field C"  }
             node: {title:"CS"
            label:"Struct foo\n\f01field A\n\f02field B\n\f11field C"  }
             node: {title:"DS"
            label:"Struct foo\n\f01field A\n\f02field B\n\f11field C"  }
         edge: { color: orange sourcename:"A" targetname:"AS" anchor: 3 }
         edge: { color: orange sourcename:"B" targetname:"BS" anchor: 3 }
         edge: { color: orange sourcename:"C" targetname:"CS" anchor: 3 }
         edge: { color: orange sourcename:"D" targetname:"DS" anchor: 3 }

             node: {title:"X1" }
             node: {title:"X2" }
             node: {title:"X3" }
             node: {title:"Y1" }
             node: {title:"Y2" }
             node: {title:"Y3" }
             node: {title:"Z1" }
             node: {title:"Z2" }
             node: {title:"Z3" }

         edge: { color: blue sourcename:"AS" targetname:"X1" anchor: 2 }
         edge: { color: red sourcename:"AS" targetname:"X2" anchor: 3 }
         edge: { color: darkyellow sourcename:"AS" targetname:"X3" anchor: 4 }
         edge: { color: blue sourcename:"BS" targetname:"Y1" anchor: 2 }
         edge: { color: red sourcename:"BS" targetname:"Y2" anchor: 3 }
         edge: { color: darkyellow sourcename:"BS" targetname:"Y3" anchor: 4 }
         edge: { color: blue sourcename:"CS" targetname:"Z1" anchor: 2 }
         edge: { color: red sourcename:"CS" targetname:"Z2" anchor: 3 }
         edge: { color: darkyellow sourcename:"CS" targetname:"Z3" anchor: 4 }
    }

The resulting graph is:

4   Further Reading

reStructured Text on Siafoo

Graph::Easy documentation

GraphViz documentation (you probably want the reference pages towards the top)

VCG homepage

[1]Magic because Siafoo is written in Python and Graph:Easy in Perl (hint: pyperl).