Welcome to graph-tool’s documentation!

Welcome to graph-tool’s documentation!#

graph-tool is an efficient Python module for manipulation and statistical analysis of graphs (a.k.a. networks).

The graph_tool module provides a Graph class and several algorithms that operate on it. The internals of this class, and of most algorithms, are written in C++ for performance, using template metaprogramming for code specialization, and the Boost Graph Library.

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

Besides superior performance, graph-tool contains the following set of functionalities 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 [descriptive-vs-inferential] for why you should avoid off-the-shelf methods available in other software packages.)

  2. Support for OpenMP shared memory parallelism for several algorithms. See the parallel algorithms section fore more information.

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

  4. 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.

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

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

  7. Support for writing custom C++ extensions.

Installing graph-tool#

Detailed installation instructions for various platforms are available here.

The easiest option is to use conda:

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

For HPC systems it is also straightforward to use graph_tool with Apptainer/Singularity.

Getting started#

Yous should read first the quick start guide, followed by the various cookbooks and explore all the examples in various submodules. For commonly asked questions, read the FAQ.

Asking questions and reporting bugs#

If you have questions about using graph-tool, you are welcome to visit the discussion forum.

If you encounter a problem, open an issue in the git repository.

Please don’t forget to check if your question has been asked before, or if a similar issue is open. When asking questions or reporting problems, it is important to include:

  1. Your exact graph-tool version.

  2. Your operating system.

  3. A minimal working example that shows the problem.

Item 3 above is very important! If you provide us only the part of the code that you believe causes the problem, then it is not possible to understand the context that may have contributed to it.

How to use the documentation#

Documentation is available in two forms: docstrings provided with the code, and the full documentation available in the graph-tool homepage.

We recommend exploring the docstrings using IPython, an advanced Python shell with TAB-completion and introspection capabilities.

The docstring examples assume that graph_tool.all has been imported as gt:

>>> import graph_tool.all as gt

Code snippets are indicated by three greater-than signs:

>>> x = x + 1

Use the built-in help function to view a function’s docstring:

>>> help(gt.Graph)

References#

[descriptive-vs-inferential]

Tiago P. Peixoto, “Descriptive vs. inferential community detection in networks: pitfalls, myths and half-truths”, Elements in the Structure and Dynamics of Complex Networks, Cambridge University Press (2023), DOI: 10.1017/9781009118897 [sci-hub, @tor] arXiv: 2112.00183

Contents#