# Tutorial

This page is a detailed tutorial of igraph’s Python capabilities. To get an quick impression of what igraph can do, check out the Quick Start. If you have not installed igraph yet, follow the section titled Installing igraph.

Note

For the impatient reader, see the Gallery of Examples page for short, self-contained examples.

## Starting igraph

The most common way to use igraph is as a named import within a Python environment (e.g. a bare Python shell, an IPython shell, a Jupyter notebook or JupyterLab instance, Google Colab, or an IDE):

    $ python
    Python 3.9.6 (default, Jun 29 2021, 05:25:02)
    [Clang 12.0.5 (clang-1205.0.22.9)] on darwin
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import igraph as ig

To call functions, you need to prefix them with `ig` (or whatever name you chose):

    >>> import igraph as ig
    >>> print(ig.__version__)
    0.9.8

Note

It is possible to use star imports for igraph:

    >>> from igraph import *

but it is generally discouraged.

There is a second way to start igraph, which is to call the script igraph from your terminal:

    $ igraph
    No configuration file, using defaults
    igraph 0.9.6 running inside Python 3.9.6 (default, Jun 29 2021, 05:25:02)
    Type "copyright", "credits" or "license" for more information.
    >>>

Note

Windows users will find the script inside the `scripts` subdirectory of Python and might have to add it manually to their path.

This script starts an appropriate shell (IPython or IDLE if found, otherwise a pure Python shell) and uses star imports (see above). This is sometimes convenient to play with igraph’s functions.

Note

You can specify which shell should be used by this script via igraph’s Configuration file.

This tutorial will assume you have imported igraph using the namespace `ig`.

## Creating a graph

The simplest way to create a graph is the `Graph` constructor. To make an empty graph:

    >>> g = ig.Graph()

To make a graph with 10 nodes (numbered `0` to `9`) and two edges connecting nodes `0-1` and `0-5`:

    >>> g = ig.Graph(n=10, edges=[[0, 1], [0, 5]])

We can print the graph to get a summary of its nodes and edges:

    >>> print(g)
    IGRAPH U--- 10 2 --
    + edges:
    0--1 0--5

This means: U ndirected graph with 10 vertices and 2 edges, with the exact edges listed out. If the graph has a name attribute, it is printed as well.

Note

igraph also has a `igraph.summary()` function, which is similar to `print()` but it does not list the edges. This is convenient for large graphs with millions of edges:

    >>> ig.summary(g)
    IGRAPH U--- 10 2 --

## Adding/deleting vertices and edges

Let’s start from the empty graph again. To add vertices to an existing graph, use `Graph.add_vertices()`:

    >>> g = ig.Graph()
    >>> g.add_vertices(3)

In igraph, vertices are always numbered up from zero. The number of a vertex is called the vertex ID. A vertex might or might not have a name.

Similarly, to add edges use `Graph.add_edges()`:

    >>> g.add_edges([(0, 1), (1, 2)])

Edges are added by specifying the source and target vertex for each edge. This call added two edges, one connecting vertices `0` and `1`, and one connecting vertices `1` and `2`. Edges are also numbered up from zero (the edge ID) and have an optional name.

Warning

Creating an empty graph and adding vertices and edges as shown here can be much slower than creating a graph with its vertices and edges as demonstrated earlier. If speed is of concern, you should especially avoid adding vertices and edges one at a time. If you need to do it anyway, you can use `Graph.add_vertex()` and `Graph.add_edge()`.

If you try to add edges to vertices with invalid IDs (i.e., you try to add an edge to vertex `5` when the graph has only three vertices), you get an `igraph.InternalError` exception:

    >>> g.add_edges([(5, 4)])
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
      File "/usr/lib/python3.10/site-packages/igraph/__init__.py", line 376, in add_edges
        res = GraphBase.add_edges(self, es)
    igraph._igraph.InternalError: Error at src/graph/type_indexededgelist.c:270: cannot add edges. -- Invalid vertex id

The message tries to explain what went wrong (`cannot add edges. -- Invalid vertex id`) along with the corresponding line in the source code where the error occurred.

Note

The whole traceback, including info on the source code, is useful when reporting bugs on our GitHub issue page. Please include it if you create a new issue!

Let us add some more vertices and edges to our graph:

    >>> g.add_edges([(2, 0)])
    >>> g.add_vertices(3)
    >>> g.add_edges([(2, 3), (3, 4), (4, 5), (5, 3)])
    >>> print(g)
    IGRAPH U---- 6 7 --
    + edges:
    0--1 1--2 0--2 2--3 3--4 4--5 3--5

We now have an undirected graph with 6 vertices and 7 edges. Vertex and edge IDs are always continuous, so if you delete a vertex all subsequent vertices will be renumbered. When a vertex is renumbered, edges are not renumbered, but their source and target vertices will. Use `Graph.delete_vertices()` and `Graph.delete_edges()` to perform these operations. For instance, to delete the edge connecting vertices `2-3`, get its ID and then delete it:

    >>> g.get_eid(2, 3)
    3
    >>> g.delete_edges(3)

## Generating graphs

igraph includes both deterministic and stochastic graph generators (see Graph generation). Deterministic generators produce the same graph every time you call the fuction, e.g.:

    >>> g = ig.Graph.Tree(127, 2)
    >>> summary(g)
    IGRAPH U--- 127 126 --

uses `Graph.Tree()` to generate a regular tree graph with 127 vertices, each vertex having two children (and one parent, of course). No matter how many times you call `Graph.Tree()`, the generated graph will always be the same if you use the same parameters:

    >>> g2 = ig.Graph.Tree(127, 2)
    >>> g2.get_edgelist() == g.get_edgelist()
    True

The above code snippet also shows you that the `get_edgelist()` method, which returns a list of source and target vertices for all edges, sorted by edge ID. If you print the first 10 elements, you get:

    >>> g2.get_edgelist()[:10]
    [(0, 1), (0, 2), (1, 3), (1, 4), (2, 5), (2, 6), (3, 7), (3, 8), (4, 9), (4, 10)]

Stochastic generators produce a different graph each time, e.g. `Graph.GRG()`:

    >>> g = ig.Graph.GRG(100, 0.2)
    >>> summary(g)
    IGRAPH U---- 100 516 --
    + attr: x (v), y (v)

Note

`+ attr` shows attributes for vertices (v) and edges (e), in this case two vertex attributes and no edge attributes.

This generates a geometric random graph: n points are chosen randomly and uniformly inside the unit square and pairs of points closer to each other than a predefined distance d are connected by an edge. If you generate GRGs with the same parameters, they will be different:

    >>> g2 = ig.Graph.GRG(100, 0.2)
    >>> g.get_edgelist() == g2.get_edgelist()
    False

A slightly looser way to check if the graphs are equivalent is via `isomorphic()`:

    >>> g.isomorphic(g2)
    False

Checking for isomorphism can take a while for large graphs (in this case, the answer can quickly be given by checking the degree distributions of the two graphs).

## Setting and retrieving attributes

As mentioned above, vertices and edges of a graph in igraph have numeric IDs from `0` upwards. Deleting vertices or edges can therefore cause reassignments of vertex and/or edge IDs. In addition to IDs, vertices and edges can have attributes such as a name, coordinates for plotting, metadata, and weights. The graph itself can have such attributes too (e.g. a name, which will show in `print` or `Graph.summary()`). In a sense, every `Graph`, vertex and edge can be used as a Python dictionary to store and retrieve these attributes.

To demonstrate the use of attributes, let us create a simple social network:

    >>> g = ig.Graph([(0,1), (0,2), (2,3), (3,4), (4,2), (2,5), (5,0), (6,3), (5,6)])

Each vertex represents a person, so we want to store names, ages and genders:

    >>> g.vs["name"] = ["Alice", "Bob", "Claire", "Dennis", "Esther", "Frank", "George"]
    >>> g.vs["age"] = [25, 31, 18, 47, 22, 23, 50]
    >>> g.vs["gender"] = ["f", "m", "f", "m", "f", "m", "m"]
    >>> g.es["is_formal"] = [False, False, True, True, True, False, True, False, False]

`Graph.vs` and `Graph.es` are the standard way to obtain a sequence of all vertices and edges, respectively. Just like a Python dictionary, we can set each property using square brackets. The value must be a list with the same length as the vertices (for `Graph.vs`) or edges (for `Graph.es`). This assigns an attribute to all vertices/edges at once.

To assign or modify an attribute for a single vertex/edge, you can use indexing:

    >>> g.es[0]["is_formal"] = True

In fact, a single vertex is represented via the class `Vertex`, and a single edge via `Edge`. Both of them plus `Graph` can all be keyed like a dictionary to set attributes, e.g. to add a date to the graph:

    >>> g["date"] = "2009-01-10"
    >>> print(g["date"])
    2009-01-10

To retrieve a dictionary of attributes, you can use `Graph.attributes()`, `Vertex.attributes()`, and `Edge.attributes()`.

Furthermore, each `Vertex` has a special property, `Vertex.index`, that is used to find out the ID of a vertex. Each `Edge` has `Edge.index` plus two additional properties, `Edge.source` and `Edge.target`, that are used to find the IDs of the vertices connected by this edge. To get both at once as a tuple, you can use `Edge.tuple`.

To assign attributes to a subset of vertices or edges, you can use slicing:

    >>> g.es[:1]["is_formal"] = True

The output of `g.es[:1]` is an instance of `EdgeSeq`, whereas `VertexSeq` is the equivalent class representing subsets of vertices.

To delete attributes, use the Python keyword `del`, e.g.:

    >>> g.vs[3]["foo"] = "bar"
    >>> g.vs["foo"]
    [None, None, None, 'bar', None, None, None]
    >>> del g.vs["foo"]
    >>> g.vs["foo"]
    Traceback (most recent call last):
      File "<stdin>", line 25, in <module>
    KeyError: 'Attribute does not exist'

Warning

Attributes can be arbitrary Python objects, but if you are saving graphs to a file, only string and numeric attributes will be kept. See the `pickle` module in the standard Python library if you are looking for a way to save other attribute types. You can either pickle your attributes individually, store them as strings and save them, or you can pickle the whole `Graph` if you know that you want to load the graph back into Python only.

## Structural properties of graphs

Besides the simple graph and attribute manipulation routines described above, igraph provides a large set of methods to calculate various structural properties of graphs. It is beyond the scope of this tutorial to document all of them, hence this section will only introduce a few of them for illustrative purposes. We will work on the small social network we built in the previous section.

Probably the simplest property one can think of is the vertex degree. The degree of a vertex equals the number of edges adjacent to it. In case of directed networks, we can also define in-degree (the number of edges pointing towards the vertex) and out-degree (the number of edges originating from the vertex). igraph is able to calculate all of them using a simple syntax:

    >>> g.degree()
    [3, 1, 4, 3, 2, 3, 2]

If the graph was directed, we would have been able to calculate the in- and out-degrees separately using `g.degree(mode="in")` and `g.degree(mode="out")`. You can also pass a single vertex ID or a list of vertex IDs to `degree()` if you want to calculate the degrees for only a subset of vertices:

    >>> g.degree(6)
    2
    >>> g.degree([2,3,4])
    [4, 3, 2]

This calling convention applies to most of the structural properties igraph can calculate. For vertex properties, the methods accept a vertex ID or a list of vertex IDs (and if they are omitted, the default is the set of all vertices). For edge properties, the methods accept a single edge ID or a list of edge IDs. Instead of a list of IDs, you can also supply a `VertexSeq` or an `EdgeSeq` instance appropriately. Later in the next chapter, you will learn how to restrict them to exactly the vertices or edges you want.

Note

For some measures, it does not make sense to calculate them only for a few vertices or edges instead of the whole graph, as it would take the same time anyway. In this case, the methods won’t accept vertex or edge IDs, but you can still restrict the resulting list later using standard list indexing and slicing operators. One such example is eigenvector centrality (`Graph.evcent()`).

Besides degree, igraph includes built-in routines to calculate many other centrality properties, including vertex and edge betweenness (`Graph.betweenness`, `Graph.edge_betweenness`) or Google’s PageRank (`Graph.pagerank()`) just to name a few. Here we just illustrate edge betweenness:

    >>> g.edge_betweenness()
    [6.0, 6.0, 4.0, 2.0, 4.0, 3.0, 4.0, 3.0. 4.0]

Now we can also figure out which connections have the highest betweenness centrality with some Python magic:

    >>> ebs = g.edge_betweenness()
    >>> max_eb = max(ebs)
    >>> [g.es[idx].tuple for idx, eb in enumerate(ebs) if eb == max_eb]
    [(0, 1), (0, 2)]

Most structural properties can also be retrieved for a subset of vertices or edges or for a single vertex or edge by calling the appropriate method on the `VertexSeq`, `EdgeSeq`, `Vertex` or `Edge` object of interest:

    >>> g.vs.degree()
    [3, 1, 4, 3, 2, 3, 2]
    >>> g.es.edge_betweenness()
    [6.0, 6.0, 4.0, 2.0, 4.0, 3.0, 4.0, 3.0. 4.0]
    >>> g.vs[2].degree()
    4

## Querying vertices and edges based on attributes

### Selecting vertices and edges

Imagine that in a given social network, you would like to find out who has the largest degree or betweenness centrality. You can do that with the tools presented so far and some basic Python knowledge, but since it is a common task to select vertices and edges based on attributes or structural properties, igraph gives you an easier way to do that:

    >>> g.vs.select(_degree=g.maxdegree())["name"]
    ['Claire']

The syntax may seem a little bit awkward for the first sight, so let’s try to interpret it step by step. `select()` is a method of `VertexSeq` and its sole purpose is to filter a `VertexSeq` based on the properties of individual vertices. The way it filters the vertices depends on its positional and keyword arguments. Positional arguments (the ones without an explicit name like `_degree` above) are always processed before keyword arguments as follows:

- If the first positional argument is `None`, an empty sequence (containing no vertices) is returned:

      >>> seq = g.vs.select(None)
      >>> len(seq)
      0

- If the first positional argument is a callable object (i.e., a function, a bound method or anything that behaves like a function), the object will be called for every vertex that’s currently in the sequence. If the function returns `True`, the vertex will be included, otherwise it will be excluded:

      >>> graph = ig.Graph.Full(10)
      >>> only_odd_vertices = graph.vs.select(lambda vertex: vertex.index % 2 == 1)
      >>> len(only_odd_vertices)
      5

- If the first positional argument is an iterable (i.e., a list, a generator or anything that can be iterated over), it must return integers and these integers will be considered as indices into the current vertex set (which is not necessarily the whole graph). Only those vertices that match the given indices will be included in the filtered vertex set. Floats, strings, invalid vertex IDs will silently be ignored:

      >>> seq = graph.vs.select([2, 3, 7])
      >>> len(seq)
      3
      >>> [v.index for v in seq]
      [2, 3, 7]
      >>> seq = seq.select([0, 2])         # filtering an existing vertex set
      >>> [v.index for v in seq]
      [2, 7]
      >>> seq = graph.vs.select([2, 3, 7, "foo", 3.5])
      >>> len(seq)
      3

- If the first positional argument is an integer, all remaining arguments are also expected to be integers and they are interpreted as indices into the current vertex set. This is just syntactic sugar, you could achieve an equivalent effect by passing a list as the first positional argument, but this way you can omit the square brackets:

      >>> seq = graph.vs.select(2, 3, 7)
      >>> len(seq)
      3

Keyword arguments can be used to filter the vertices based on their attributes or their structural properties. The name of each keyword argument should consist of at most two parts: the name of the attribute or structural property and the filtering operator. The operator can be omitted; in that case, we automatically assume the equality operator. The possibilities are as follows (where name denotes the name of the attribute or property):

Keyword argument | Meaning
--- | ---
`name_eq` | The attribute/property value must be equal to the value of the keyword argument
`name_ne` | The attribute/property value must not be equal to the value of the keyword argument
`name_lt` | The attribute/property value must be less than the value of the keyword argument
`name_le` | The attribute/property value must be less than or equal to the value of the keyword argument
`name_gt` | The attribute/property value must be greater than the value of the keyword argument
`name_ge` | The attribute/property value must be greater than or equal to the value of the keyword argument
`name_in` | The attribute/property value must be included in the value of the keyword argument, which must be a sequence in this case
`name_notin` | The attribute/property value must not be included in the value of the the keyword argument, which must be a sequence in this case

For instance, the following command gives you people younger than 30 years in our imaginary social network:

    >>> g.vs.select(age_lt=30)

Note

Due to the syntactical constraints of Python, you cannot use the admittedly simpler syntax of `g.vs.select(age < 30)` as only the equality operator is allowed to appear in an argument list in Python.

To save you some typing, you can even omit the `select()` method if you wish:

    >>> g.vs(age_lt=30)

Theoretically, it can happen that there exists an attribute and a structural property with the same name (e.g., you could have a vertex attribute named `degree`). In that case, we would not be able to decide whether the user meant `degree` as a structural property or as a vertex attribute. To resolve this ambiguity, structural property names must always be preceded by an underscore (`_`) when used for filtering. For example, to find vertices with degree larger than 2:

    >>> g.vs(_degree_gt=2)

There are also a few special structural properties for selecting edges:

- Using `_source` or `_from` in the keyword argument list of `EdgeSeq.select()` filters based on the source vertices of the edges. E.g., to select all the edges originating from Claire (who has vertex index 2):

      >>> g.es.select(_source=2)

- Using `_target` or `_to` filters based on the target vertices. This is different from `_source` and `_from` if the graph is directed.

- `_within` takes a `VertexSeq` object or a list or set of vertex indices and selects all the edges that originate and terminate in the given vertex set. For instance, the following expression selects all the edges between Claire (vertex index 2), Dennis (vertex index 3) and Esther (vertex index 4):

      >>> g.es.select(_within=[2,3,4])

  We could also have used a `VertexSeq` object:

      >>> g.es.select(_within=g.vs[2:5])

- `_between` takes a tuple consisting of two `VertexSeq` objects or lists containing vertex indices or `Vertex` objects and selects all the edges that originate in one of the sets and terminate in the other. E.g., to select all the edges that connect men to women:

      >>> men = g.vs.select(gender="m")
      >>> women = g.vs.select(gender="f")
      >>> g.es.select(_between=(men, women))

### Finding a single vertex or edge with some properties

In many cases we are looking for a single vertex or edge of a graph with some properties, and either we do not care which one of the matches is returned if there are multiple matches, or we know in advance that there will be only one match. A typical example is looking up vertices by their names in the `name` property. `VertexSeq` and `EdgeSeq` objects provide the `find()` method for such use-cases. `find()` works similarly to `select()`, but it returns only the first match if there are multiple matches, and throws an exception if no match is found. For instance, to look up the vertex corresponding to Claire, one can do this:

    >>> claire = g.vs.find(name="Claire")
    >>> type(claire)
    igraph.Vertex
    >>> claire.index
    2

Looking up an unknown name will yield an exception:

    >>> g.vs.find(name="Joe")
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ValueError: no such vertex

### Looking up vertices by names

Looking up vertices by names is a very common operation, and it is usually much easier to remember the names of the vertices in a graph than their IDs. To this end, igraph treats the `name` attribute of vertices specially; they are indexed such that vertices can be looked up by their names in amortized constant time. To make things even easier, igraph accepts vertex names (almost) anywhere where it expects vertex IDs, and also accepts collections (list, tuples etc) of vertex names anywhere where it expects lists of vertex IDs or `VertexSeq` instances. E.g, you can simply look up the degree (number of connections) of Dennis as follows:

    >>> g.degree("Dennis")
    3

or, alternatively:

    >>> g.vs.find("Dennis").degree()
    3

The mapping between vertex names and IDs is maintained transparently by igraph in the background; whenever the graph changes, igraph also updates the internal mapping. However, uniqueness of vertex names is not enforced; you can easily create a graph where two vertices have the same name, but igraph will return only one of them when you look them up by names, the other one will be available only by its index.

## Treating a graph as an adjacency matrix

Adjacency matrix is another way to form a graph. In adjacency matrix, rows and columns are labeled by graph vertices: the elements of the matrix indicate whether the vertices i and j have a common edge (i, j). The adjacency matrix for the example graph is

    >>> g.get_adjacency()
    Matrix([
      [0, 1, 1, 0, 0, 1, 0],
      [1, 0, 0, 0, 0, 0, 0],
      [1, 0, 0, 1, 1, 1, 0],
      [0, 0, 1, 0, 1, 0, 1],
      [0, 0, 1, 1, 0, 0, 0],
      [1, 0, 1, 0, 0, 0, 1],
      [0, 0, 0, 1, 0, 1, 0]
    ])

For example, Claire (`[1, 0, 0, 1, 1, 1, 0]`) is directly connected to Alice (who has vertex index 0), Dennis (index 3), Esther (index 4), and Frank (index 5), but not to Bob (index 1) nor George (index 6).

## Layouts and plotting

A graph is an abstract mathematical object without a specific representation in 2D or 3D space. This means that whenever we want to visualise a graph, we have to find a mapping from vertices to coordinates in two- or three-dimensional space first, preferably in a way that is pleasing for the eye. A separate branch of graph theory, namely graph drawing, tries to solve this problem via several graph layout algorithms. igraph implements quite a few layout algorithms and is also able to draw them onto the screen or to a PDF, PNG or SVG file using the Cairo library.

Important

To follow the examples of this subsection, you need the Python bindings of the Cairo library or matplotlib (depending on what backend is selected). The previous chapter (Installing igraph) tells you more about how to install Cairo’s Python bindings.

### Layout algorithms

The layout methods in igraph are to be found in the `Graph` object, and they always start with `layout_`. The following table summarises them:

Method name | Short name | Algorithm description
--- | --- | ---
`layout_circle` | `circle`, `circular` | Deterministic layout that places the vertices on a circle
`layout_davidson_harel` | `dh` | Davidson-Harel simulated annealing algorithm
`layout_drl` | `drl` | The Distributed Recursive Layout algorithm for large graphs
`layout_fruchterman_reingold` | `fr` | Fruchterman-Reingold force-directed algorithm
`layout_fruchterman_reingold_3d` | `fr3d`, `fr_3d` | Fruchterman-Reingold force-directed algorithm in three dimensions
`layout_graphopt` | `graphopt` | The GraphOpt algorithm for large graphs
`layout_grid` | `grid` | Regular grid layout
`layout_kamada_kawai` | `kk` | Kamada-Kawai force-directed algorithm
`layout_kamada_kawai_3d` | `kk3d`, `kk_3d` | Kamada-Kawai force-directed algorithm in three dimensions
`layout_lgl` | `large`, `lgl`, `large_graph` | The Large Graph Layout algorithm for large graphs
`layout_mds` | `mds` | Multidimensional scaling layout
`layout_random` | `random` | Places the vertices completely randomly
`layout_random_3d` | `random_3d` | Places the vertices completely randomly in 3D
`layout_reingold_tilford` | `rt`, `tree` | Reingold-Tilford tree layout, useful for (almost) tree-like graphs
`layout_reingold_tilford_circular` | `rt_circular` | Reingold-Tilford tree layout with a polar coordinate post-transformation, useful for (almost) tree-like graphs
`layout_sphere` | `sphere`, `spherical`, `circular_3d` | Deterministic layout that places the vertices evenly on the surface of a sphere

Layout algorithms can either be called directly or using the common layout method called `layout()`:

    >>> layout = g.layout_kamada_kawai()
    >>> layout = g.layout("kamada_kawai")

The first argument of the `layout()` method must be the short name of the layout algorithm (see the table above). All the remaining positional and keyword arguments are passed intact to the chosen layout method. For instance, the following two calls are completely equivalent:

    >>> layout = g.layout_reingold_tilford(root=[2])
    >>> layout = g.layout("rt", root=[2])

Layout methods return a `Layout` object, which behaves mostly like a list of lists. Each list entry in a `Layout` object corresponds to a vertex in the original graph and contains the vertex coordinates in the 2D or 3D space. `Layout` objects also contain some useful methods to translate, scale or rotate the coordinates in a batch. However, the primary utility of `Layout` objects is that you can pass them to the `plot()` function along with the graph to obtain a 2D drawing.

### Drawing a graph using a layout

For instance, we can plot our imaginary social network with the Kamada-Kawai layout algorithm as follows:

    >>> layout = g.layout("kk")
    >>> ig.plot(g, layout=layout)

This should open an external image viewer showing a visual representation of the network, something like the one on the following figure (although the exact placement of nodes may be different on your machine since the layout is not deterministic):

Our social network with the Kamada-Kawai layout algorithm

If you prefer to use matplotlib as a plotting engine, create an axes and use the `target` argument:

    >>> import matplotlib.pyplot as plt
    >>> fig, ax = plt.subplots()
    >>> ig.plot(g, layout=layout, target=ax)

Note

When plotting rooted trees, Cairo automatically puts the root on top of the image and the leaves at the bottom. For matplotlib, the root is usually at the bottom instead. You can easily place the root on top by calling ax.invert_yaxis().

Hmm, this is not too pretty so far. A trivial addition would be to use the names as the vertex labels and to color the vertices according to the gender. Vertex labels are taken from the `label` attribute by default and vertex colors are determined by the `color` attribute, so we can simply create these attributes and re-plot the graph:

    >>> g.vs["label"] = g.vs["name"]
    >>> color_dict = {"m": "blue", "f": "pink"}
    >>> g.vs["color"] = [color_dict[gender] for gender in g.vs["gender"]]
    >>> ig.plot(g, layout=layout, bbox=(300, 300), margin=20)  # Cairo backend
    >>> ig.plot(g, layout=layout, target=ax)  # matplotlib backend

Note that we are simply re-using the previous layout object here, but for the Cairo backend we also specified that we need a smaller plot (300 x 300 pixels) and a larger margin around the graph to fit the labels (20 pixels). These settings would be ignored for the Matplotlib backend. The result is:

Our social network - with names as labels and genders as colors

and for matplotlib:

Our social network - with names as labels and genders as colors

Instead of specifying the visual properties as vertex and edge attributes, you can also give them as keyword arguments to `plot()`:

    >>> color_dict = {"m": "blue", "f": "pink"}
    >>> ig.plot(g, layout=layout, vertex_color=[color_dict[gender] for gender in g.vs["gender"]])

This latter approach is preferred if you want to keep the properties of the visual representation of your graph separate from the graph itself. You can simply set up a Python dictionary containing the keyword arguments you would pass to `plot()` and then use the double asterisk (`**`) operator to pass your specific styling attributes to `plot()`:

    >>> visual_style = {}
    >>> visual_style["vertex_size"] = 20
    >>> visual_style["vertex_color"] = [color_dict[gender] for gender in g.vs["gender"]]
    >>> visual_style["vertex_label"] = g.vs["name"]
    >>> visual_style["edge_width"] = [1 + 2 * int(is_formal) for is_formal in g.es["is_formal"]]
    >>> visual_style["layout"] = layout
    >>> visual_style["bbox"] = (300, 300)
    >>> visual_style["margin"] = 20
    >>> ig.plot(g, **visual_style)

The final plot shows the formal ties with thick lines while informal ones with thin lines:

Our social network - also showing which ties are formal

To sum it all up: there are special vertex and edge properties that correspond to the visual representation of the graph. These attributes override the default settings of igraph (see Configuration for overriding the system-wide defaults). Furthermore, appropriate keyword arguments supplied to `plot()` override the visual properties provided by the vertex and edge attributes. The following two tables summarise the most frequently used visual attributes for vertices and edges, respectively:

### Vertex attributes controlling graph plots

Attribute name | Keyword argument | Purpose
--- | --- | ---
`color` | `vertex_color` | Color of the vertex
`font` | `vertex_font` | Font family of the vertex
`label` | `vertex_label` | Label of the vertex
`label_angle` | `vertex_label_angle` | The placement of the vertex label on the circle around the vertex. This is an angle in radians, with zero belonging to the right side of the vertex.
`label_color` | `vertex_label_color` | Color of the vertex label
`label_dist` | `vertex_label_dist` | Distance of the vertex label from the vertex itself, relative to the vertex size
`label_size` | `vertex_label_size` | Font size of the vertex label
`order` | `vertex_order` | Drawing order of the vertices. Vertices with a smaller order parameter will be drawn first.
`shape` | `vertex_shape` | Shape of the vertex. Known shapes are: `rectangle`, `circle`, `diamond`, `hidden`, `triangle-up`, `triangle-down`. Several aliases are also accepted, see `drawing.known_shapes`.
`size` | `vertex_size` | Size of the vertex in pixels

### Edge attributes controlling graph plots

Attribute name | Keyword argument | Purpose
--- | --- | ---
`color` | `edge_color` | Color of the edge
`curved` | `edge_curved` | The curvature of the edge. Positive values correspond to edges curved in CCW direction, negative numbers correspond to edges curved in clockwise (CW) direction. Zero represents straight edges. `True` is interpreted as 0.5, `False` is interpreted as zero. This is useful to make multiple edges visible. See also the `autocurve` keyword argument to `plot()`.
`font` | `edge_font` | Font family of the edge
`arrow_size` | `edge_arrow_size` | Size (length) of the arrowhead on the edge if the graph is directed, relative to 15 pixels.
`arrow_width` | `edge_arrow_width` | Width of the arrowhead on the edge if the graph is directed, relative to 10 pixels.
`loop_size` | `edge_loop_size` | Size of self-loops. It can be set as a negative number, in which case it scales with the size of the corresponding vertex (e.g. -1.0 means the loop has the same size as the vertex). This attribute is ignored by edges that are not loops. This attribute is available only in the matplotlib backend.
`width` | `edge_width` | Width of the edge in pixels.
`label` | `edge_label` | If specified, it adds a label to the edge.
`background` | `edge_background` | If specified, it adds a rectangular box around the edge label, of the specified color (matplotlib only).
`align_label` | `edge_align_label` | If True, rotate the edge label such that it aligns with the edge direction. Labels that would be upside-down are flipped (matplotlib only).

### Generic keyword arguments of `plot()`

These settings can be specified as keyword arguments to the `plot()` function to control the overall appearance of the plot.

Keyword argument | Purpose
--- | ---
`autocurve` | Whether to determine the curvature of the edges automatically in graphs with multiple edges. The default is `True` for graphs with less than 10.000 edges and `False` otherwise.
`bbox` | The bounding box of the plot. This must be a tuple containing the desired width and height of the plot. The default plot is 600 pixels wide and 600 pixels high. Ignored for the Matplotlib backend.
`layout` | The layout to be used. It can be an instance of `Layout`, a list of tuples containing X-Y coordinates, or the name of a layout algorithm. The default is `auto`, which selects a layout algorithm automatically based on the size and connectedness of the graph.
`margin` | The top, right, bottom and left margins of the plot in pixels. This argument must be a list or tuple and its elements will be re-used if you specify a list or tuple with less than four elements. Ignored for the Matplotlib backend.

### Specifying colors in plots

igraph understands the following color specifications wherever it expects a color (e.g., edge, vertex or label colors in the respective attributes):

X11 color names

  See the list of X11 color names in Wikipedia for the complete list. Alternatively you can see the keys of the `igraph.drawing.colors.known_colors` dictionary. Color names are case insensitive in igraph so `"DarkBlue"` can be written as `"darkblue"` as well.

Color specification in CSS syntax

  This is a string according to one of the following formats (where R, G and B denote the red, green and blue components, respectively):

  - `#RRGGBB`, components range from 0 to 255 in hexadecimal format. Example: `"#0088ff"`.

  - `#RGB`, components range from 0 to 15 in hexadecimal format. Example: `"#08f"`.

  - `rgb(R, G, B)`, components range from 0 to 255 or from 0% to 100%. Example: `"rgb(0, 127, 255)"` or `"rgb(0%, 50%, 100%)"`.

Lists or tuples of RGB values in the range 0-1

  Example: `(1.0, 0.5, 0)` or `[1.0, 0.5, 0]`.

Note that when specifying the same color for all vertices or edges, you can use a string as-is but not the tuple or list syntax as tuples or lists would be interpreted as if the items in the tuple are for individual vertices or edges. So, this would work:

    >>> ig.plot(g, vertex_color="green")

But this would not, as it would treat the items in the tuple as palette indices for the first, second and third vertoces:

    >>> ig.plot(g, vertex_color=(1, 0, 0))

In this latter case, you need to expand the color specification for each vertex explicitly:

    >>> ig.plot(g, vertex_color=[(1, 0, 0)] * g.vcount())

### Saving plots

igraph can be used to create publication-quality plots by asking the `plot()` function to save the plot into a file instead of showing it on a screen. This can be done simply by passing the target filename as an additional argument after the graph itself. The preferred format is inferred from the extension. igraph can save to anything that is supported by Cairo, including SVG, PDF and PNG files. SVG or PDF files can then later be converted to PostScript (`.ps`) or Encapsulated PostScript (`.eps`) format if you prefer that, while PNG files can be converted to TIF (`.tif`):

    >>> ig.plot(g, "social_network.pdf", **visual_style)

If you are using the matplotlib backend, you can save your plot as usual:

    >>> fig, ax = plt.subplots()
    >>> ig.plot(g, **visual_style)
    >>> fig.savefig("social_network.pdf")

Many file formats are supported by matplotlib.

## igraph and the outside world

No graph module would be complete without some kind of import/export functionality that enables the package to communicate with external programs and toolkits. igraph is no exception: it provides functions to read the most common graph formats and to save `Graph` objects into files obeying these format specifications. The following table summarises the formats igraph can read or write:

Format | Short name | Reader method | Writer method
--- | --- | --- | ---
Adjacency list | `lgl` | `Graph.Read_Lgl()` | `Graph.write_lgl()`
(a.k.a. LGL) |  |  |
Adjacency matrix | `adjacency` | `Graph.Read_Adjacency()` | `Graph.write_adjacency()`
DIMACS | `dimacs` | `Graph.Read_DIMACS()` | `Graph.write_dimacs()`
DL | `dl` | `Graph.Read_DL()` | not supported yet
Edge list | `edgelist`, `edges`, `edge` | `Graph.Read_Edgelist()` | `Graph.write_edgelist()`
GraphViz | `graphviz`, `dot` | not supported yet | `Graph.write_dot()`
GML | `gml` | `Graph.Read_GML()` | `Graph.write_gml()`
GraphML | `graphml` | `Graph.Read_GraphML()` | `Graph.write_graphml()`
Gzipped GraphML | `graphmlz` | `Graph.Read_GraphMLz()` | `Graph.write_graphmlz()`
LEDA | `leda` | not supported yet | `Graph.write_leda()`
Labeled edgelist | `ncol` | `Graph.Read_Ncol()` | `Graph.write_ncol()`
(a.k.a. NCOL) |  |  |
Pajek format | `pajek`, `net` | `Graph.Read_Pajek()` | `Graph.write_pajek()`
Pickled graph | `pickle` | `Graph.Read_Pickle()` | `Graph.write_pickle()`

As an exercise, download the graph representation of the well-known Zachary karate club study from `this file`, unzip it and try to load it into igraph. Since it is a GraphML file, you must use the GraphML reader method from the table above (make sure you use the appropriate path to the downloaded file):

    >>> karate = ig.Graph.Read_GraphML("zachary.graphml")
    >>> ig.summary(karate)
    IGRAPH UNW- 34 78 -- Zachary's karate club network

If you want to convert the very same graph into, say, Pajek’s format, you can do it with the Pajek writer method from the table above:

    >>> karate.write_pajek("zachary.net")

Note

Most of the formats have their own limitations; for instance, not all of them can store attributes. Your best bet is probably GraphML or GML if you want to save igraph graphs in a format that can be read from an external package and you want to preserve numeric and string attributes. Edge list and NCOL is also fine if you don’t have attributes (NCOL supports vertex names and edge weights, though). If you don’t want to use your graphs outside igraph but you want to store them for a later session, the pickled graph format ensures that you get exactly the same graph back. The pickled graph format uses Python’s `pickle` module to store and read graphs.

There are two helper methods as well: `read()` is a generic entry point for reader methods which tries to infer the appropriate format from the file extension. `Graph.write()` is the opposite of `read()`: it lets you save a graph where the preferred format is again inferred from the extension. The format detection of `read()` and `Graph.write()` can be overridden by the `format` keyword argument which accepts the short names of the formats from the above table:

    >>> karate = ig.load("zachary.graphml")
    >>> karate.write("zachary.net")
    >>> karate.write("zachary.my_extension", format="gml")

## Where to go next

This tutorial was only scratching the surface of what igraph can do. My long-term plans are to extend this tutorial into a proper manual-style documentation to igraph in the next chapters. In the meanwhile, check out the API reference which should provide information about almost every igraph class, function or method. A good starting point is the documentation of the `Graph` class. Should you get stuck, try asking in our Discourse group first - maybe there is someone out there who can help you out immediately.