Note

This documents the development version of PyGraphviz. Documentation for the current release can be found here.

AGraph Class

class AGraph(thing=None, filename=None, data=None, string=None, handle=None, name='', strict=True, directed=False, **attr)[source]

Class for Graphviz agraph type.

Example use

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G = pgv.AGraph(directed=True)
>>> G = pgv.AGraph("file.dot")  

Graphviz graph keyword parameters are processed so you may add them like

>>> G = pgv.AGraph(landscape="true", ranksep="0.1")

or alternatively

>>> G = pgv.AGraph()
>>> G.graph_attr.update(landscape="true", ranksep="0.1")

and

>>> G.node_attr.update(color="red")
>>> G.edge_attr.update(len="2.0", color="blue")

See http://www.graphviz.org/doc/info/attrs.html for a list of attributes.

Keyword parameters:

thing is a generic input type (filename, string, handle to pointer, dictionary of dictionaries). An attempt is made to automaticaly detect the type so you may write for example:

>>> d = {"1": {"2": None}, "2": {"1": None, "3": None}, "3": {"2": None}}
>>> A = pgv.AGraph(d)
>>> s = A.to_string()
>>> B = pgv.AGraph(s)
>>> h = B.handle
>>> C = pgv.AGraph(h)

Parameters:

name:    Name for the graph

strict: True|False (True for simple graphs)

directed: True|False

data: Dictionary of dictionaries or dictionary of lists
representing nodes or edges to load into initial graph

string:  String containing a dot format graph

handle:  Swig pointer to an agraph_t data structure
Attributes
directed

Return True if graph is directed or False if not.

name
strict

Return True if graph is strict or False if not.

Methods

acyclic([args, copy])

Reverse sufficient edges in digraph to make graph acyclic.

add_cycle(nlist)

Add the cycle of nodes given in nlist.

add_edge(u[, v, key])

Add a single edge between nodes u and v.

add_edges_from(ebunch, **attr)

Add nodes to graph from a container ebunch.

add_node(n, **attr)

Add a single node n.

add_nodes_from(nbunch, **attr)

Add nodes from a container nbunch.

add_path(nlist)

Add the path of nodes given in nlist.

add_subgraph([nbunch, name])

Return subgraph induced by nodes in nbunch.

clear()

Remove all nodes, edges, and attributes from the graph.

copy()

Return a copy of the graph.

degree([nbunch, with_labels])

Return the degree of nodes given in nbunch container.

degree_iter([nbunch, indeg, outdeg])

Return an iterator over the degree of the nodes given in nbunch container.

delete_edge(u[, v, key])

Remove edge between nodes u and v from the graph.

delete_edges_from(ebunch)

Remove edges from ebunch (a container of edges).

delete_node(n)

Remove the single node n.

delete_nodes_from(nbunch)

Remove nodes from a container nbunch.

delete_subgraph(name)

Remove subgraph with given name.

draw([path, format, prog, args])

Output graph to path in specified format.

edges([nbunch, keys])

Return list of edges in the graph.

edges_iter([nbunch, keys])

Return iterator over edges in the graph.

from_string(string)

Load a graph from a string in dot format.

get_edge(u, v[, key])

Return an edge object (Edge) corresponding to edge (u,v).

get_node(n)

Return a node object (Node) corresponding to node n.

get_subgraph(name)

Return existing subgraph with specified name or None if it doesn't exist.

has_edge(u[, v, key])

Return True an edge u-v is in the graph or False if not.

has_neighbor(u, v[, key])

Return True if u has an edge to v or False if not.

has_node(n)

Return True if n is in the graph or False if not.

in_degree([nbunch, with_labels])

Return the in-degree of nodes given in nbunch container.

in_degree_iter([nbunch])

Return an iterator over the in-degree of the nodes given in nbunch container.

in_edges([nbunch, keys])

Return list of in edges in the graph.

in_edges_iter([nbunch, keys])

Return iterator over out edges in the graph.

in_neighbors(n)

Return list of predecessor nodes of n.

is_directed()

Return True if graph is directed or False if not.

is_strict()

Return True if graph is strict or False if not.

is_undirected()

Return True if graph is undirected or False if not.

iterdegree([nbunch, indeg, outdeg])

Return an iterator over the degree of the nodes given in nbunch container.

iteredges([nbunch, keys])

Return iterator over edges in the graph.

iterindegree([nbunch])

Return an iterator over the in-degree of the nodes given in nbunch container.

iterinedges([nbunch, keys])

Return iterator over out edges in the graph.

iterneighbors(n)

Return iterator over the nodes attached to n.

iternodes()

Return an iterator over all the nodes in the graph.

iteroutdegree([nbunch])

Return an iterator over the out-degree of the nodes given in nbunch container.

iteroutedges([nbunch, keys])

Return iterator over out edges in the graph.

iterpred(n)

Return iterator over predecessor nodes of n.

itersucc(n)

Return iterator over successor nodes of n.

layout([prog, args])

Assign positions to nodes in graph.

neighbors(n)

Return a list of the nodes attached to n.

neighbors_iter(n)

Return iterator over the nodes attached to n.

nodes()

Return a list of all nodes in the graph.

nodes_iter()

Return an iterator over all the nodes in the graph.

number_of_edges()

Return the number of edges in the graph.

number_of_nodes()

Return the number of nodes in the graph.

order()

Return the number of nodes in the graph.

out_degree([nbunch, with_labels])

Return the out-degree of nodes given in nbunch container.

out_degree_iter([nbunch])

Return an iterator over the out-degree of the nodes given in nbunch container.

out_edges([nbunch, keys])

Return list of out edges in the graph.

out_edges_iter([nbunch, keys])

Return iterator over out edges in the graph.

out_neighbors(n)

Return list of successor nodes of n.

predecessors(n)

Return list of predecessor nodes of n.

predecessors_iter(n)

Return iterator over predecessor nodes of n.

read(path)

Read graph from dot format file on path.

remove_edge(u[, v, key])

Remove edge between nodes u and v from the graph.

remove_edges_from(ebunch)

Remove edges from ebunch (a container of edges).

remove_node(n)

Remove the single node n.

remove_nodes_from(nbunch)

Remove nodes from a container nbunch.

remove_subgraph(name)

Remove subgraph with given name.

reverse()

Return copy of directed graph with edge directions reversed.

string()

Return a string (unicode) representation of graph in dot format.

string_nop()

Return a string (unicode) representation of graph in dot format.

subgraph([nbunch, name])

Return subgraph induced by nodes in nbunch.

subgraph_parent([nbunch, name])

Return parent graph of subgraph or None if graph is root graph.

subgraph_root([nbunch, name])

Return root graph of subgraph or None if graph is root graph.

subgraphs()

Return a list of all subgraphs in the graph.

subgraphs_iter()

Iterator over subgraphs.

successors(n)

Return list of successor nodes of n.

successors_iter(n)

Return iterator over successor nodes of n.

to_directed(**kwds)

Return directed copy of graph.

to_string()

Return a string representation of graph in dot format.

to_undirected()

Return undirected copy of graph.

tred([args, copy])

Transitive reduction of graph.

unflatten([args])

Adjust directed graphs to improve layout aspect ratio.

write([path])

Write graph in dot format to file on path.

close

get_name

acyclic(args='', copy=False)[source]

Reverse sufficient edges in digraph to make graph acyclic. Modifies existing graph.

To create a new graph use

>>> import pygraphviz as pgv
>>> A = pgv.AGraph(directed=True)
>>> B = A.acyclic(copy=True)  

See the graphviz “acyclic” program for details of the algorithm.

add_cycle(nlist)[source]

Add the cycle of nodes given in nlist.

add_edge(u, v=None, key=None, **attr)[source]

Add a single edge between nodes u and v.

If the nodes u and v are not in the graph they will added.

If u and v are not strings, conversion to a string will be attempted. String conversion will work if u and v have valid string representation (try str(u) if you are unsure).

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_edge("a", "b")
>>> G.edges()
[('a', 'b')]

The optional key argument allows assignment of a key to the edge. This is especially useful to distinguish between parallel edges in multi-edge graphs (strict=False).

>>> G = pgv.AGraph(strict=False)
>>> G.add_edge("a", "b", "first")
>>> G.add_edge("a", "b", "second")
>>> sorted(G.edges(keys=True))
[('a', 'b', 'first'), ('a', 'b', 'second')]

Attributes can be added when edges are created or updated after creation

>>> G.add_edge("a", "b", color="green")

Attributes must be valid strings.

See http://www.graphviz.org/doc/info/attrs.html for a list of attributes.

add_edges_from(ebunch, **attr)[source]

Add nodes to graph from a container ebunch.

ebunch is a container of edges such as a list or dictionary.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> elist = [("a", "b"), ("b", "c")]
>>> G.add_edges_from(elist)

Attributes can be added when edges are created or updated after creation

>>> G.add_edges_from(elist, color="green")
add_node(n, **attr)[source]

Add a single node n.

If n is not a string, conversion to a string will be attempted. String conversion will work if n has valid string representation (try str(n) if you are unsure).

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_node("a")
>>> G.nodes()
['a']
>>> G.add_node(1)  # will be converted to a string
>>> G.nodes()
['a', '1']

Attributes can be added to nodes on creation or updated after creation (attribute values must be strings)

>>> G.add_node(2, color="red")

See http://www.graphviz.org/doc/info/attrs.html for a list of attributes.

Anonymous Graphviz nodes are currently not implemented.

add_nodes_from(nbunch, **attr)[source]

Add nodes from a container nbunch.

nbunch can be any iterable container such as a list or dictionary

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> nlist = ["a", "b", 1, "spam"]
>>> G.add_nodes_from(nlist)
>>> sorted(G.nodes())
['1', 'a', 'b', 'spam']

Attributes can be added to nodes on creation or updated after creation

>>> G.add_nodes_from(nlist, color="red")  # set all nodes in nlist red
add_path(nlist)[source]

Add the path of nodes given in nlist.

add_subgraph(nbunch=None, name=None, **attr)[source]

Return subgraph induced by nodes in nbunch.

clear()[source]

Remove all nodes, edges, and attributes from the graph.

close()[source]
copy()[source]

Return a copy of the graph.

Notes

Versions <=1.6 made a copy by writing and the reading a dot string. This version loads a new graph with nodes, edges and attributes.

degree(nbunch=None, with_labels=False)[source]

Return the degree of nodes given in nbunch container.

Using optional with_labels=True returns a dictionary keyed by node with value set to the degree.

degree_iter(nbunch=None, indeg=True, outdeg=True)[source]

Return an iterator over the degree of the nodes given in nbunch container.

Returns pairs of (node,degree).

delete_edge(u, v=None, key=None)

Remove edge between nodes u and v from the graph.

With optional key argument will only remove an edge matching (u,v,key).

delete_edges_from(ebunch)

Remove edges from ebunch (a container of edges).

delete_node(n)

Remove the single node n.

Attempting to remove a node that isn’t in the graph will produce an error.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_node("a")
>>> G.remove_node("a")
delete_nodes_from(nbunch)

Remove nodes from a container nbunch.

nbunch can be any iterable container such as a list or dictionary

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> nlist = ["a", "b", 1, "spam"]
>>> G.add_nodes_from(nlist)
>>> G.remove_nodes_from(nlist)
delete_subgraph(name)

Remove subgraph with given name.

property directed

Return True if graph is directed or False if not.

draw(path=None, format=None, prog=None, args='')[source]

Output graph to path in specified format.

An attempt will be made to guess the output format based on the file extension of path. If that fails, then the format parameter will be used.

Note, if path is a file object returned by a call to os.fdopen(), then the method for discovering the format will not work. In such cases, one should explicitly set the format parameter; otherwise, it will default to ‘dot’.

If path is None, the result is returned as a Bytes object.

Formats (not all may be available on every system depending on how Graphviz was built)

‘canon’, ‘cmap’, ‘cmapx’, ‘cmapx_np’, ‘dia’, ‘dot’, ‘fig’, ‘gd’, ‘gd2’, ‘gif’, ‘hpgl’, ‘imap’, ‘imap_np’, ‘ismap’, ‘jpe’, ‘jpeg’, ‘jpg’, ‘mif’, ‘mp’, ‘pcl’, ‘pdf’, ‘pic’, ‘plain’, ‘plain-ext’, ‘png’, ‘ps’, ‘ps2’, ‘svg’, ‘svgz’, ‘vml’, ‘vmlz’, ‘vrml’, ‘vtx’, ‘wbmp’, ‘xdot’, ‘xlib’

If prog is not specified and the graph has positions (see layout()) then no additional graph positioning will be performed.

Optional prog=[‘neato’|’dot’|’twopi’|’circo’|’fdp’|’nop’] will use specified graphviz layout method.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_edges_from([(0, 1), (1, 2), (2, 0), (2, 3)])
>>> G.layout()

# use current node positions, output pdf in ‘file.pdf’ >>> G.draw(“file.pdf”)

# use dot to position, output png in ‘file’ >>> G.draw(“file”, format=”png”, prog=”dot”)

# use keyword ‘args’ to pass additional arguments to graphviz >>> G.draw(“test.pdf”, prog=”twopi”, args=”-Gepsilon=1”) >>> G.draw(“test2.pdf”, args=”-Nshape=box -Edir=forward -Ecolor=red “)

The layout might take a long time on large graphs.

edges(nbunch=None, keys=False)[source]

Return list of edges in the graph.

If the optional nbunch (container of nodes) only edges adjacent to nodes in nbunch will be returned.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_edge("a", "b")
>>> G.add_edge("c", "d")
>>> print(sorted(G.edges()))
[('a', 'b'), ('c', 'd')]
>>> print(G.edges("a"))
[('a', 'b')]
edges_iter(nbunch=None, keys=False)[source]

Return iterator over edges in the graph.

If the optional nbunch (container of nodes) only edges adjacent to nodes in nbunch will be returned.

Note: modifying the graph structure while iterating over edges may produce unpredictable results. Use edges() as an alternative.

from_string(string)[source]

Load a graph from a string in dot format.

Overwrites any existing graph.

To make a new graph from a string use

>>> import pygraphviz as pgv
>>> s = "digraph {1 -> 2}"
>>> A = pgv.AGraph()
>>> t = A.from_string(s)
>>> A = pgv.AGraph(string=s)  # specify s is a string
>>> A = pgv.AGraph(s)  # s assumed to be a string during initialization
get_edge(u, v, key=None)[source]

Return an edge object (Edge) corresponding to edge (u,v).

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_edge("a", "b")
>>> edge = G.get_edge("a", "b")
>>> print(edge)
('a', 'b')

With optional key argument will only get edge matching (u,v,key).

get_name()[source]
get_node(n)[source]

Return a node object (Node) corresponding to node n.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_node("a")
>>> node = G.get_node("a")
>>> print(node)
a
get_subgraph(name)[source]

Return existing subgraph with specified name or None if it doesn’t exist.

has_edge(u, v=None, key=None)[source]

Return True an edge u-v is in the graph or False if not.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_edge("a", "b")
>>> G.has_edge("a", "b")
True

Optional key argument will restrict match to edges (u,v,key).

has_neighbor(u, v, key=None)[source]

Return True if u has an edge to v or False if not.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_edge("a", "b")
>>> G.has_neighbor("a", "b")
True

Optional key argument will only find edges (u,v,key).

has_node(n)[source]

Return True if n is in the graph or False if not.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_node("a")
>>> G.has_node("a")
True
>>> "a" in G  # same as G.has_node('a')
True
in_degree(nbunch=None, with_labels=False)[source]

Return the in-degree of nodes given in nbunch container.

Using optional with_labels=True returns a dictionary keyed by node with value set to the degree.

in_degree_iter(nbunch=None)[source]

Return an iterator over the in-degree of the nodes given in nbunch container.

Returns pairs of (node,degree).

in_edges(nbunch=None, keys=False)[source]

Return list of in edges in the graph. If the optional nbunch (container of nodes) only in edges adjacent to nodes in nbunch will be returned.

in_edges_iter(nbunch=None, keys=False)[source]

Return iterator over out edges in the graph.

If the optional nbunch (container of nodes) only out edges adjacent to nodes in nbunch will be returned.

Note: modifying the graph structure while iterating over edges may produce unpredictable results. Use in_edges() as an alternative.

in_neighbors(n)

Return list of predecessor nodes of n.

is_directed()[source]

Return True if graph is directed or False if not.

is_strict()[source]

Return True if graph is strict or False if not.

Strict graphs do not allow parallel edges or self loops.

is_undirected()[source]

Return True if graph is undirected or False if not.

iterdegree(nbunch=None, indeg=True, outdeg=True)

Return an iterator over the degree of the nodes given in nbunch container.

Returns pairs of (node,degree).

iteredges(nbunch=None, keys=False)

Return iterator over edges in the graph.

If the optional nbunch (container of nodes) only edges adjacent to nodes in nbunch will be returned.

Note: modifying the graph structure while iterating over edges may produce unpredictable results. Use edges() as an alternative.

iterindegree(nbunch=None)

Return an iterator over the in-degree of the nodes given in nbunch container.

Returns pairs of (node,degree).

iterinedges(nbunch=None, keys=False)

Return iterator over out edges in the graph.

If the optional nbunch (container of nodes) only out edges adjacent to nodes in nbunch will be returned.

Note: modifying the graph structure while iterating over edges may produce unpredictable results. Use in_edges() as an alternative.

iterneighbors(n)

Return iterator over the nodes attached to n.

Note: modifying the graph structure while iterating over node neighbors may produce unpredictable results. Use neighbors() as an alternative.

iternodes()

Return an iterator over all the nodes in the graph.

Note: modifying the graph structure while iterating over the nodes may produce unpredictable results. Use nodes() as an alternative.

iteroutdegree(nbunch=None)

Return an iterator over the out-degree of the nodes given in nbunch container.

Returns pairs of (node,degree).

iteroutedges(nbunch=None, keys=False)

Return iterator over out edges in the graph.

If the optional nbunch (container of nodes) only out edges adjacent to nodes in nbunch will be returned.

Note: modifying the graph structure while iterating over edges may produce unpredictable results. Use out_edges() as an alternative.

iterpred(n)

Return iterator over predecessor nodes of n.

Note: modifying the graph structure while iterating over node predecessors may produce unpredictable results. Use predecessors() as an alternative.

itersucc(n)

Return iterator over successor nodes of n.

Note: modifying the graph structure while iterating over node successors may produce unpredictable results. Use successors() as an alternative.

layout(prog='neato', args='')[source]

Assign positions to nodes in graph.

Optional prog=[‘neato’|’dot’|’twopi’|’circo’|’fdp’|’nop’] will use specified graphviz layout method.

>>> import pygraphviz as pgv
>>> A = pgv.AGraph()
>>> A.add_edge(1, 2)
>>> A.layout()
>>> A.layout(prog="neato", args="-Nshape=box -Efontsize=8")

Use keyword args to add additional arguments to graphviz programs.

The layout might take a long time on large graphs.

property name
neighbors(n)[source]

Return a list of the nodes attached to n.

neighbors_iter(n)[source]

Return iterator over the nodes attached to n.

Note: modifying the graph structure while iterating over node neighbors may produce unpredictable results. Use neighbors() as an alternative.

nodes()[source]

Return a list of all nodes in the graph.

nodes_iter()[source]

Return an iterator over all the nodes in the graph.

Note: modifying the graph structure while iterating over the nodes may produce unpredictable results. Use nodes() as an alternative.

number_of_edges()[source]

Return the number of edges in the graph.

number_of_nodes()[source]

Return the number of nodes in the graph.

order()[source]

Return the number of nodes in the graph.

out_degree(nbunch=None, with_labels=False)[source]

Return the out-degree of nodes given in nbunch container.

Using optional with_labels=True returns a dictionary keyed by node with value set to the degree.

out_degree_iter(nbunch=None)[source]

Return an iterator over the out-degree of the nodes given in nbunch container.

Returns pairs of (node,degree).

out_edges(nbunch=None, keys=False)[source]

Return list of out edges in the graph.

If the optional nbunch (container of nodes) only out edges adjacent to nodes in nbunch will be returned.

out_edges_iter(nbunch=None, keys=False)[source]

Return iterator over out edges in the graph.

If the optional nbunch (container of nodes) only out edges adjacent to nodes in nbunch will be returned.

Note: modifying the graph structure while iterating over edges may produce unpredictable results. Use out_edges() as an alternative.

out_neighbors(n)

Return list of successor nodes of n.

predecessors(n)[source]

Return list of predecessor nodes of n.

predecessors_iter(n)[source]

Return iterator over predecessor nodes of n.

Note: modifying the graph structure while iterating over node predecessors may produce unpredictable results. Use predecessors() as an alternative.

read(path)[source]

Read graph from dot format file on path.

path can be a file name or file handle

use:

G.read('file.dot')
remove_edge(u, v=None, key=None)[source]

Remove edge between nodes u and v from the graph.

With optional key argument will only remove an edge matching (u,v,key).

remove_edges_from(ebunch)[source]

Remove edges from ebunch (a container of edges).

remove_node(n)[source]

Remove the single node n.

Attempting to remove a node that isn’t in the graph will produce an error.

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> G.add_node("a")
>>> G.remove_node("a")
remove_nodes_from(nbunch)[source]

Remove nodes from a container nbunch.

nbunch can be any iterable container such as a list or dictionary

>>> import pygraphviz as pgv
>>> G = pgv.AGraph()
>>> nlist = ["a", "b", 1, "spam"]
>>> G.add_nodes_from(nlist)
>>> G.remove_nodes_from(nlist)
remove_subgraph(name)[source]

Remove subgraph with given name.

reverse()[source]

Return copy of directed graph with edge directions reversed.

property strict

Return True if graph is strict or False if not.

Strict graphs do not allow parallel edges or self loops.

string()[source]

Return a string (unicode) representation of graph in dot format.

string_nop()[source]

Return a string (unicode) representation of graph in dot format.

subgraph(nbunch=None, name=None, **attr)

Return subgraph induced by nodes in nbunch.

subgraph_parent(nbunch=None, name=None)[source]

Return parent graph of subgraph or None if graph is root graph.

subgraph_root(nbunch=None, name=None)[source]

Return root graph of subgraph or None if graph is root graph.

subgraphs()[source]

Return a list of all subgraphs in the graph.

subgraphs_iter()[source]

Iterator over subgraphs.

successors(n)[source]

Return list of successor nodes of n.

successors_iter(n)[source]

Return iterator over successor nodes of n.

Note: modifying the graph structure while iterating over node successors may produce unpredictable results. Use successors() as an alternative.

to_directed(**kwds)[source]

Return directed copy of graph.

Each undirected edge u-v is represented as two directed edges u->v and v->u.

to_string()[source]

Return a string representation of graph in dot format.

to_string() uses “agwrite” to produce “dot” format w/o rendering. The function string_nop() layouts with “nop” and renders to “dot”.

to_undirected()[source]

Return undirected copy of graph.

tred(args='', copy=False)[source]

Transitive reduction of graph. Modifies existing graph.

To create a new graph use

>>> import pygraphviz as pgv
>>> A = pgv.AGraph(directed=True)
>>> B = A.tred(copy=True)  

See the graphviz “tred” program for details of the algorithm.

unflatten(args='')[source]

Adjust directed graphs to improve layout aspect ratio.

>>> import pygraphviz as pgv
>>> A = pgv.AGraph()
>>> A_unflattened = A.unflatten("-f -l 3")
>>> A.unflatten("-f -l 1").layout()

Use keyword args to add additional arguments to graphviz programs.

write(path=None)[source]

Write graph in dot format to file on path.

path can be a file name or file handle

use:

G.write('file.dot')