What is graph-tool?

Graph-tool is an efficient Python module for manipulation and statistical analysis of graphs (a.k.a. networks). Contrary to most other Python modules with similar functionality, the core data structures and algorithms are implemented in C++, making extensive use of template metaprogramming, based heavily on the Boost Graph Library. This confers it a level of performance that is comparable (both in memory usage and computation time) to that of a pure C/C++ library.

Graph-tool is mature software that has been on the cutting edge of network science for more than 15 years. It is fully documented, and is released as Free Software under the LGPLv3 license.

Important

Graph-tool can be orders of magnitude faster than Python-only alternatives, and therefore it is specially suited for large-scale network analysis.

Tip

After installation, you should start with the quick start guide!

You should then take a look at the various cookbooks, and explore all the examples in the various submodules.

For commonly asked questions, read the FAQ.

Newest version: 2.80

See the changelog.

Quick installation:

Conda

conda create --name gt -c conda-forge graph-tool
conda activate gt

Pixi

mkdir my-project
cd my-project
pixi init
pixi add graph-tool

Homebrew

brew install graph-tool

Arch

pikaur -S python-graph-tool

Debian/Ubuntu

apt-get install python3-graph-tool

(see the intructions for installing the bleeding edge version from the upstream repository.)

Gentoo

emerge graph-tool

Fedora

dnf install python3-graph-tool

Docker

docker pull tiagopeixoto/graph-tool

Note

See here for more detailed installation instructions.

Tip

For a quick test run without installing on your machine, you can run graph-tool under colab.

Unique features

These are some of the functionalities of graph-tool which are currently not available in most other comparable packages:

1. Comprehensive framework for inferential community detection, build upon statistically principled approaches that avoid overfitting and are interpretable. (See here as well as  [1] for why you should avoid off-the-shelf methods available in other software packages.)

2. Support for network reconstruction from dynamics.

3. Support for uncertainty quantification in network data.

4. Support for OpenMP shared memory parallelism for several algorithms.

5. High-quality network visualization, both static and interactive, supporting animations and matplotlib integration.

6. Filtered graphs, i.e. graphs where nodes and edges are temporarily masked. These are first class citizens in the library, and are accepted by every function. Due to the use of C++ template metaprogramming, this functionality comes at no performance cost when filtering is not being used.

7. Efficient and fully documented binary format for network files.

8. Integration with the Netzschleuder network data repository, enabling easy loading of network data.

9. Support for writing custom C++ extensions.

Quick demos:

Hierarchical community detection

Output

Code

import graph_tool.all as gt
import matplotlib.cm

gt.seed_rng(47)

g = gt.collection.ns["foodweb_baywet"]

sargs = dict(recs=[g.ep.weight],
             rec_types=["real-exponential"])
state = \
    gt.minimize_nested_blockmodel_dl(g,
                                     state_args=sargs)

state.draw(edge_color=gt.prop_to_size(g.ep.weight,
                                      power=1,
                                      log=True),
           ecmap=(matplotlib.cm.inferno, .6),
           eorder=g.ep.weight,
           edge_pen_width=gt.prop_to_size(g.ep.weight,
                                          1, 4,
                                          power=1,
                                          log=True),
           edge_gradient=[]);

Pagerank

Output

Code

import graph_tool.all as gt
import matplotlib.cm

g = gt.collection.data["polblogs"]

g = gt.extract_largest_component(g)
pr = gt.pagerank(g)

gt.graph_draw(g, pos=g.vp["pos"],
              vertex_fill_color=pr,
              vertex_size=gt.prop_to_size(pr,
                                          mi=5,
                                          ma=15),
              vorder=pr,
              vcmap=matplotlib.cm.gist_heat);

Opinion dynamics

Output

Code

import graph_tool.all as gt

g = gt.collection.data["polblogs"]
g = gt.GraphView(g, directed=False)
gt.remove_parallel_edges(g)
g = gt.extract_largest_component(g)

s = g.vp.value.t(lambda x: 2 * x - 1)

state = gt.IsingGlauberState(g, s=s, beta=.1)

state.iterate_async(niter=1000 * g.num_vertices())

gt.graph_draw(g, g.vp.pos,
              vertex_fill_color=state.s);

Triangulation

Output

Code

import graph_tool.all as gt
from numpy.random import random
from scipy.linalg import norm

points = random((500, 2)) * 4

g, pos = gt.triangulation(points, type="delaunay")
weight = g.new_edge_property("double")

for e in g.edges():
    weight[e] = norm(pos[e.source()].a -
                     pos[e.target()].a)

b = gt.betweenness(g, weight=weight)

gt.graph_draw(g, pos=pos, vertex_fill_color=b[0],
              edge_pen_width=b[1].t(lambda x: x*120));

SBMs

Output

Code

import graph_tool.all as gt

g = gt.collection.data["polblogs"]

g = gt.extract_largest_component(g, prune=True)

state = gt.minimize_blockmodel_dl(g)

u = gt.generate_sbm(state.b.a,
                    gt.adjacency(state.get_bg(),
                                 state.get_ers()).T,
                    g.degree_property_map("out").a,
                    g.degree_property_map("in").a,
                    directed=True)

gt.graph_draw(u, g.vp.pos);

It is fast!

Despite its nice, soft outer appearance of a regular Python module, the core algorithms and data structures of graph-tool are written in C++, with performance in mind. Most of the time, you can expect the algorithms to run just as fast as if graph-tool were a pure C/C++ library. See a performance comparison.

OpenMP support

Many algorithms are implemented in parallel using OpenMP, which provides excellent performance on multi-core architectures, without degrading it on single-core machines.

Comprehensive functionality

An extensive array of features is included, such as support for arbitrary vertex, edge or graph properties, efficient “on the fly” filtering of vertices and edges, powerful graph I/O using the GraphML, GML and dot file formats, graph pickling, graph statistics (degree/property histogram, vertex correlations, average shortest distance, etc.), centrality measures, standard structural algorithms (isomorphism, minimum spanning tree, connected components, dominator tree, maximum flow, etc.), generation of random graphs with arbitrary degrees and correlations, detection of modules and communities via statistical inference, and much more.

Powerful visualization

Conveniently draw your graphs, using a variety of algorithms and output formats (including to the screen). Graph-tool has its own layout algorithms and versatile, interactive drawing routines based on cairo and GTK+, but it can also work as a very comfortable interface to the excellent graphviz package.

Fully documented

Every single function in the module is documented in the docstrings and in the online documentation, which is full of examples.

References

[1]

T. P. Peixoto, Descriptive Vs. Inferential Community Detection in Networks: Pitfalls, Myths and Half-Truths, Elements in the Structure and Dynamics of Complex Networks (2023).