Table of Contents
What is graph-tool?
graph-tool is a powerful Python script module for graph manipulation and statistical analysis (a.k.a. networks). In contrast to most other Python modules with similar functionality, the core data structures and algorithms are written in C++, with extensive use of template metaprogramming and a heavy reliance on the Boost Graph Library. This gives it performance comparable to a pure C/C++ library (in terms of memory usage and computation time).
If you are looking for a decent introduction to basic knowledge in graph and network visualization, check out my article for Embarcadero Technologies here.
Why graph-tool?
The following are the reasons why graph-tool might be the best network and graph visualization tools out there:
1. Fast
Most of the time, you can expect the algorithms to run just as fast as if graph-tool were a pure C/C++ library.
The following table shows brief performance comparisons between graph-tool and two other popular graph libraries with Python bindings, igraph and NetworkX [2]:
| Algorithm | graph-tool (16 threads) | graph-tool (1 thread) | igraph | NetworkX |
| Single-source shortest path | 0.0023 s | 0.0022 s | 0.0092 s | 0.25 s |
| Global clustering | 0.011 s | 0.025 s | 0.027 s | 7.94 s |
| PageRank | 0.0052 s | 0.022 s | 0.072 s | 1.54 s |
| K-core | 0.0033 s | 0.0036 s | 0.0098 s | 0.72 s |
| Minimum spanning tree | 0.0073 s | 0.0072 s | 0.026 s | 0.64 s |
| Betweenness | 102 s (~1.7 mins) | 331 s (~5.5 mins) | 198 s (vertex)+ 439 s (edge)(~ 10.6 mins) | 10297 s (vertex)13913 s (edge)(~6.7 hours) |
Note: The test was performed by calling the functions several times, and calculating the average time taken per function call. The hardware used for this test is Intel(R) Core(TM) i9-9980HK CPU @ 2.40GHz with 8 cores and 16 threads. The results for graph-tool with OpenMP enabled using 16 threads are shown in the second column, and the results using only one thread are shown in the third column.
When OpenMP is disabled, both graph-tool and igraph appear to deliver comparable overall performance. Even in this case, graph-tool appears to be faster systematically.
2. OpenMP (Open Multi-Processing) support
Provides excellent performance on multi-core architectures, without degrading it on single-core machines.
3. Extensive features
Including an extensive array of features, 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 topological 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.
4. Powerful visualization
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.
5. Well documented
Every single function in the module is documented in the docstrings and in the online documentation [3], which is full of examples.
How to install graph-tool on Windows?
We cannot directly install graph-tool on Windows. For now, graph-tool is not supported in Windows, even installation with conda on Windows would also fail. On other OS, you can successfully install graph-tool via conda, by adding the ostrokach-forge channel [4].
In this article, we will demonstrate two ways of installation: Installing graph-tool using Docker Desktop and using Anaconda on WSL (Windows Subsystem for Linux).
How to install graph-tool on Windows using Docker Desktop?
The best solution and OS-agnostic way to install graph-tool is using Docker. In this section, we will demonstrate the step-by-step in installing graph-tool using Docker, to assist you; in case you have little or no familiarity with using Docker. The following are the step-by-step graph-tool installation using Docker Desktop, for Windows users:
If you already install Docker on your Windows correctly, run the following command on your cmd to pull the graph-tool image:
|
1 |
docker pull tiagopeixoto/graph-tool |
Open Docker Desktop, go to the Images tab, and run the graph-tool image:
Go to Optional settings, to give your container a representative name, for example, graph-tool-python:
Open the container, by going to the Containers tab, and run the graph-tool-python container:
And graph-tool would be installed and run successfully.
How to install graph-tool on Windows using Anaconda on WSL?
This section assumes you are already familiar with Linux on Windows using WSL (Windows Subsystem for Linux) [5], and you already installed Anaconda on your Linux system [6]. In this demo, I installed graph-tool on Ubuntu 18.04 on WSL on Windows 10.
Why not install it directly via package managers for GNU/Linux, you might ask? As instructed in Reference [7]? If you install graph-tool directly via package managers for GNU/Linux, you might encounter the following error, that might be caused by the package is missing in the your selected distribution:
You might need to change the distribution and try it one by one (available distribution: bookworm, bullseye, buster, sid, bionic, eoan, focal, hirsute, impish, jammy), that might be too time consuming. Read more about it in Reference [8]:
So, the more straightforward way is by installing it via Anaconda.
The easiest way to install graph-tool is to create a new environment and install it there:
|
1 |
conda create --name gt -c conda-forge graph-tool |
You can also install graph-tool without creating a new environment, but the solver is likely to fail (or hang) if your environment already contains many packages, whose dependencies may conflict with the graph-tool dependencies. This is particularly likely if your environment contains packages from the official Anaconda distribution, rather than the conda-forge distribution.
Activate the newly-created graph-tool or gt environment:
|
1 |
conda activate gt |
After that, install additional packages as needed:
|
1 |
conda install -n gt -c conda-forge ipython jupyter |
How to start graph-tool interactive sessions?
with IPython (for Docker users)
Run the following line on your Windows cmd, to activate the graph-tool using interactive Python (IPython) [7]:
|
1 |
docker run -it -u user -w /home/user tiagopeixoto/graph-tool ipython |
If you successfully activate the IPython for graph-tool, your command prompt would look like the following screenshot:
with Jupyter Notebook (for WSL users)
First, activate your Anaconda environment that contains the graph-tool library:
|
1 |
conda activate gt |
Run Jupyter Notebook with this command on your Ubuntu on WSL cmd:
|
1 |
jupyter notebook |
How to create your first graphs?
The graph tool module includes a Graph class as well as several algorithms that work with it. For the best performance, the internals of this class, as well as most of its algorithms, are written in C++ using the Boost Graph Library.
Let’s create your first graph using graph-tool with the following scripts [9]:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
from graph_tool.all import * g = Graph() ug = Graph(directed=False) ug = Graph() ug.set_directed(False) assert ug.is_directed() == False g1 = Graph() g2 = Graph(g1) v1 = g.add_vertex() v2 = g.add_vertex() e = g.add_edge(v1, v2) graph_draw(g, vertex_text=g.vertex_index, output="two-nodes.png") |
A simple directed graph with two vertices and one edge would be created and saved as a two-nodes.png file by the script above.
Are there more graph-tool advanced examples?
In this section, we will try a more advanced example, that starts by loading a dataset, and then performing stochastic block model inference and visualizing the result with graph-tool.
First, we will start by loading the graph-tool dataset collection [10].
Here is the excerpt of the graph-tool dataset descriptions:
For example, we will work with the “football” dataset. Run the following scripts on the graph-tool IPython:
|
1 2 3 4 |
g = graph_tool.collection.data["football"] print(g) print(g.gp.readme) print(g.gp.description) |
And let’s infer the best partition of the network using the following scripts [11]:
|
1 2 |
state = graph_tool.inference.minimize_blockmodel_dl(g) state.draw(pos=g.vp.pos, output="football-sbm-fit.svg") |
The script above will perform stochastic block model inference of a network of American college football teams. The colors correspond to inferred group membership of the nodes.
How to browse the graph-tool plotting results?
How to show all the graph-tool plotting results by exporting the container (for Docker users)
You may notice that opening the plot results in Docker is tricky. It won’t be easily accessible as in your usual Windows’ or even Linux File Explorer.
You can see the following screenshot showing that the usual Linux or cmd commands are not working in Docker’s terminal:
To tackle this problem, and get your graph-tool outputs, you may need to archive your container’s file system into a tar file first. Open your command prompt, and run the following command [12]:
|
1 |
docker export container_name > contents.tar |
For example:
|
1 |
docker export modest_knuth > contents.tar |
The process might be time-consuming (and consuming large space as well), as it will export the entire contents of our selected container.
After the exporting contents are completed, open the contents.tar file, and go to the /home/user directory to get the file you need. For example, from our previous sections: two-nodes.pdf and football-sbm-fit.svg.
How do we browse all the graph-tool plotting results via File Explorer (for Ubuntu on WSL users)?
For long-time Windows users, you might also notice that browsing the plot results or accessing files in general using GUI in WSL is tricky too. It won’t be easily accessible as in your usual Windows’ or even native Linux File Explorer.
But, in the latest Windows 10 update, we can easily browse Linux files from File Explorer, like we usually browse Windows files.
For example on my laptop, Go to Linux -> home -> user, and you would find your graph-tool outputs:
Is there another easier alternative? Try NetworkX!
Whether graph-tool provides publication-quality outputs & collections of sophisticated algorithms, we can consider that graph-tools is not beginner friendly, due to the following reasons:
- Not easy to install or configure. The installation steps are not conventional.
- Not supported in Windows.
- If you insist on using graph-tool on Windows, the easiest way to use graph-tool is via Docker (because it is OS agnostic), as we’ve already shown in the demo above, or using dual OS employing WSL.
- By using graph-tool via Docker, it means you have limited options in using it (either with IPython or Jupyter Notebook). And using Jupyter Notebook would lead you to set up a notebook server using VM, which might increase the challenges for beginners.
- This means you can’t use it with your familiar or favorite IDEs like PyScripter, Spyder, etc.
In contrast with the challenges above, NetworkX can easily be installed via pip or conda on all OS, and can easily be used in any famous Python IDE.
We’ve reviewed NetworkX, how to install it, and all the requirements, even create Windows GUI for it in the following articles:
and you can watch the demo of NetworkX4D, along with other 5 famous Python libraries here:
In addition, if you’re looking for other powerful data visualization libraries, check out this article:
To get started with PyScripter, a free, feature-rich, and lightweight Python IDE, click here.
Download RAD Studio to make more powerful Python GUI Windows Apps in 5x less time.
Check out Python4Delphi, which simplifies the creation of Python GUIs for Windows using Delphi.
Consider DelphiVCL, which simplifies the creation of Windows GUIs with Python.
References & further readings
[1] Peixoto, T. P. (2022).
graph-tool official website. graph-tool.skewed.de
[2] Peixoto, T. P. (2022).
graph-tool performance comparison. graph-tool.skewed.de/performance
[3] Peixoto, T. P. (2022).
Welcome to graph-tool’s documentation! graph-tool 2.45 documentation. graph-tool.skewed.de/static/doc/index.html
[4] Uliana, R. (2017).
Installing graph-tool for Python 3 on Anaconda. Medium. ronie.medium.com/installing-graph-tool-for-python-3-on-anaconda-3f76d9004979
[5] Microsoft Learn. (2022).
Install Linux on Windows with WSL. learn.microsoft.com/en-us/windows/wsl/install
[6] DigitalOcean. (2018).
How To Install Anaconda on Ubuntu 18.04 [Quickstart]. digitalocean.com/community/tutorials/how-to-install-anaconda-on-ubuntu-18-04-quickstart
[7] Peixoto, T. P. (2022).
graph-tool installation instructions. graph-tool 2.45 GitLab repository. git.skewed.de/count0/graph-tool/-/wikis/installation-instructions
[8] Stack Overflow. (2020).
Error in installing graph-tool in Ubuntu 18.04. stackoverflow.com/questions/61485539/error-in-installing-graph-tool-in-ubuntu-18-04
[9] Peixoto, T. P. (2022).
Quick start using graph-tool. graph-tool 2.45 documentation. graph-tool.skewed.de/static/doc/quickstart.html
[10] Peixoto, T. P. (2022).
graph_tool.collection – Dataset collection. graph-tool 2.45 documentation. graph-tool.skewed.de/static/doc/collection.html
[11] Peixoto, T. P. (2022).
Inferring modular network structure. graph-tool 2.45 documentation. graph-tool.skewed.de/static/doc/demos/inference/ inference.html
[12] Stack Overflow. (2014).
Exploring Docker container’s file system. stackoverflow.com/questions/20813486/exploring-docker-containers-file-system
