Note

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

# Tutorial

The API is very similar to that of NetworkX. Much of the NetworkX tutorial at https://networkx.org/documentation/latest/tutorial.html is applicable to PyGraphviz. See http://pygraphviz.github.io/documentation/latest/reference/api_notes.html for major differences.

## Start-up

Import PyGraphviz with

    >>> import pygraphviz as pgv

## Graphs

To make an empty pygraphviz graph use the AGraph class:

    >>> G = pgv.AGraph()

You can use the strict and directed keywords to control what type of graph you want. The default is to create a strict graph (no parallel edges or self-loops). To create a digraph with possible parallel edges and self-loops use

    >>> G = pgv.AGraph(strict=False, directed=True)

You may specify a dot format file to be read on initialization:

    >>> G = pgv.AGraph("Petersen.dot")

Other options for intializing a graph are using a string,

    >>> G = pgv.AGraph("graph {1 - 2}")

using a dict of dicts,

    >>> d = {"1": {"2": None}, "2": {"1": None, "3": None}, "3": {"2": None}}
    >>> A = pgv.AGraph(d)

or using a SWIG pointer to the AGraph datastructure,

    >>> h = A.handle
    >>> C = pgv.AGraph(h)

## Nodes, and edges

Nodes and edges can be added one at a time

    >>> G.add_node("a")  # adds node 'a'
    >>> G.add_edge("b", "c")  # adds edge 'b'-'c' (and also nodes 'b', 'c')

or from lists or containers.

    >>> nodelist = ["f", "g", "h"]
    >>> G.add_nodes_from(nodelist)

If the node is not a string an attempt will be made to convert it to a string

    >>> G.add_node(1)  # adds node '1'

## Attributes

To set the default attributes for graphs, nodes, and edges use the graph_attr, node_attr, and edge_attr dictionaries

    >>> G.graph_attr["label"] = "Name of graph"
    >>> G.node_attr["shape"] = "circle"
    >>> G.edge_attr["color"] = "red"

Graph attributes can be set when initializing the graph

    >>> G = pgv.AGraph(ranksep="0.1")

Attributes can be added when adding nodes or edges,

    >>> G.add_node(1, color="red")
    >>> G.add_edge("b", "c", color="blue")

or through the node or edge attr dictionaries,

    >>> n = G.get_node(1)
    >>> n.attr["shape"] = "box"

    >>> e = G.get_edge("b", "c")
    >>> e.attr["color"] = "green"

## Layout and Drawing

Pygraphviz provides several methods for layout and drawing of graphs.

To store and print the graph in dot format as a Python string use

    >>> s = G.string()

To write to a file use

    >>> G.write("file.dot")

To add positions to the nodes with a Graphviz layout algorithm

    >>> G.layout()  # default to neato
    >>> G.layout(prog="dot")  # use dot

To render the graph to an image

    >>> G.draw("file.png")  # write previously positioned graph to PNG file
    >>> G.draw("file.ps", prog="circo")  # use circo to position, write PS file