tidygraph 0.4.8
tidy-like interface for network manipulation and visualization in Python
Requires Python: >=3.13

# tidygraph

[![pypi](https://img.shields.io/pypi/v/tidygraph.svg)](https://pypi.org/project/tidygraph/)
![pyversion](https://img.shields.io/pypi/pyversions/tidygraph.svg)
[![ci](https://github.com/yiping-allison/tidygraph-py/actions/workflows/ci.yaml/badge.svg)](https://github.com/yiping-allison/tidygraph-py/actions/workflows/ci.yaml)

A tidy-like API for network manipulation with the [igraph](https://github.com/igraph/python-igraph) library inspired by:

- [tidygraph](https://github.com/thomasp85/tidygraph)
- [tidygraphtool](https://github.com/jstonge/tidygraphtool/tree/main)

The main purpose of using this library on top of `python-igraph` is to support relational data manipulation.

```python
tg = Tidygraph.from_dataframe(...)
tg.activate(ActiveType.EDGES).join(..., how="outer").mutate({"rank": lambda x: 1.0 - x["score"]})
```

> [!IMPORTANT]
> This library is experimental, and updates may be infrequent. Use at your own risk.

## 📦️ Installation

This package is available on [PyPI](https://pypi.org/project/tidygraph/).

You can install plot backends (`cairo`, `matplotlib`, or `plotly`) using the `extras` option.

```sh
# Base
pip install tidygraph
uv add tidygraph

# With plot support
pip install "tidygraph[cairo]"
uv add tidygraph --optional cairo
```

## 🧑‍💻 Development

The easiest way to get started with development is through [`nix`](https://nixos.org/) and related ecosystem tools.

I recommend installing nix using either options:

- [Determinate Nix installer](https://github.com/DeterminateSystems/nix-installer)
- [Official Nix installer](https://github.com/NixOS/nix-installer)

> [!NOTE]
> The nix installer provided by the official nix team (since writing, 2026-01-16) is experimental. As a general rule of thumb,
> choose to install from Determinate Nix if you prefer the [additional functionalities](https://determinate.systems/blog/installer-dropping-upstream/)
> provided by the Determinate Nix team, otherwise, use the experimental installer for upstream.

Additionally, you will need [`direnv`](https://direnv.net/) and [`nix-direnv`](https://github.com/nix-community/nix-direnv?tab=readme-ov-file).

Most (if not all) `nix` development workflows use direnv to auto-load the nix shell environment.

The main editor of choice is [VSCode](https://code.visualstudio.com/download). Recommended extensions are included in the [workspace](./tidygraph.code-workspace) file.

The environment should just work if everything is setup correctly!

## 🚑️ FAQ

### Nix, Python, and VSCode

Unfortunately VSCode does not have a programmatic way to set which python interpreter to use. Because the python environment is managed by nix, and nix installs/builds
packages in a non-standard location, VSCode cannot auto-detect where your packages are.

You will need to update the python interpreter path whenever your nix shell environment updates.

The easiest way to do this is the following:

```sh
# print the python interpreter you are currently tracking
which python
```

The path should look something like `/nix/store/XXXXXXXXXXXXXXXXXX-venv/bin/python`. This is the python virtual environment generated by `pyproject-nix` and `uv2nix`.

Update the interpreter path in VSCode's python language settings.

> [!TIP]
> You can find the modal quickly using the command palette and searching `Python: Select Interpreter`.

### Is `Tidygraph` thread-safe?

No. Tidygraph is built on top of `igraph`, which the core C library is inherently not thread-safe.
See [official response](https://github.com/igraph/python-igraph/issues/866) for details.

## 👥 Acknowledgements

This library would not have been possible without existing work from dedicated teams:

- [`python-igraph`](https://github.com/igraph/python-igraph)
- [`tidygraph`](https://github.com/thomasp85/tidygraph/tree/main)

## 🔨 TODO

- Consider adding more verbs available in R `tidygraph`
- Cleanup test code