subgraph method in python graphviz?

Question

So I am trying to use graphviz package on python and it has a method named subgraph() but I think it's different from the definition widely used in network theory.

As far as I know, subgraph means a graph whose nodes and edges are subsets of another graph.

On graphviz user guide it says:
Add the current content of the given sole graph argument as subgraph or return a context manager returning a new graph instance created with the given (name, comment, etc.) arguments whose content is added as subgraph when leaving the context manager’s with-block.

This is an example from user guide

import graphviz
p = Graph(name='parent')
p.edge('spam', 'eggs')
c = Graph(name='child', node_attr={'shape': 'box'})
c.edge('foo', 'bar')

p.subgraph(c)

According to the network theory, graph p should have all nodes 'spam', 'eggs', 'foo', 'bar' and subgraph c should be made from nodes and edges used in graph p.

But it's not. It seems like subgraph() method just adds two graphs into one. Am I right?

And what is a special cluster subgraph? (If the name of a subgraph begins with 'cluster' the layout engine will treat it as a special cluster subgraph). I can't find any result in google.

Thank you

Answer 1

You can treat subgraph as tool for logically groupping nodes and edges.

Consider following example (if you don't mind, I will be using native Graphviz syntax, not the Python Graphviz wrapper):

digraph {
    a -> b
    c
    d -> e
    f
    g -> h
    c -> a
}

Now let's add a subgraph around nodes c, d and e and change the global node attributes, for example, give them rectangular shape and red color:

digraph {
    a -> b
    subgraph mysubgraph {
        node [shape=rect color=red]
        c
        d -> e
    }
    f
    g -> h
    c -> a
}

As you can see, nothing changed in node placement, but those nodes which were inside subgraph changed shape and color. Also, notice that you were right: we affected both c node, which is defined as a node, and d;e nodes, which were implicitly defined as an edge.

We can also use subgraphs to control node placement (and that's what subgraphs are used for most of the times) with rank attribute. To force nodes in subgraph to appear on the same line, add a rank=same attribute to your subgraph:

digraph {
    a -> b
    subgraph mysubgraph {
        node [shape=rect color=red]
        rank=same
        c
        d -> e
    }
    f
    g -> h
    c -> a
}

Clusters are a completely different story. When you add a word "cluster" to the beginning of your subgraph name, the nodes which are defined inside this cluster will be physically gathered together. You will also get a rectangle (by default) wrapping these nodes on your graph:

digraph {
    a -> b
    subgraph cluster_mysubgraph {
        node [shape=rect color=red]
        c
        d -> e
    }
    f
    g -> h
    c -> a
}

Notice the difference between this, and second picture. I suggest you to use clusters with caution. Once you have connections between nodes inside and outside your cluster, things may go weird in terms of layout.

By the way, it's really hard to learn garphviz by official docs, becuase they are more of a reference rather than guide. But they also have a nice guide, written in good language for normal people (sorry, mathematicians) but it's buried inside Graphviz website: https://graphviz.gitlab.io/_pages/pdf/dotguide.pdf