GyRAPH

A Python framework for signal processing on directed graphs.

Overview

GyRAPH provides graph shift operators for asymmetric graphs, a complex-valued Graph Fourier Transform built on their (possibly non-orthogonal) eigenbases, a family of filters that operate in the resulting spectral domain, and statistical tooling — surrogates and stationarity tests — for hypothesis testing on directed graph signals.

The library is built on NumPy, SciPy and NetworkX, and is designed to slot into existing analysis pipelines rather than replace them.

📖 Documentation: gyraph.readthedocs.io — tutorials, full API reference, and the papers behind the methods.

Key features

Installation

pip install GyRAPH

From source, for development:

git clone https://github.com/miki998/GyRAPH.git && cd GyRAPH && pip install -e .

Requires Python 3.9+. Core dependencies (NumPy, SciPy, NetworkX, scikit-learn, pandas, matplotlib/seaborn/scienceplots, sympy, tqdm) are installed automatically; the mesh and learning-oriented modules additionally pull in PyTorch, torch-geometric, OpenCV and scikit-image.

Quickstart

Building a graph and its Fourier basis

import numpy as np
from gyraph.graphs import Graph, create_directed_torus

# A directed torus: 8 rows x 6 columns, asymmetric by construction
G, pos = create_directed_torus(Nr=8, Nc=6, directed=True)
graph = Graph(G=G, pos=pos)

# Attach a shift operator — this computes the Graph Fourier basis
graph.set_operator("adjacency")            # or "laplacian", "advection_diffusion", ...
op = graph.operator

print(graph)                                # active operator, node and edge counts
print(graph.is_directed(), graph.assymetry_level())
print(op.normality())                       # 0 if the operator is normal, larger otherwise
print(op.V[:5], op.frequencies[:5])         # eigenvalues and graph frequencies

set_operator accepts "adjacency", "laplacian", "advection_diffusion", "time_vertex_laplacian" and "time_vertex_adjacency", and forwards keyword arguments to the operator — e.g. graph.set_operator("laplacian", normalize="symmetric").

Transforming and filtering a signal

from gyraph.filters import SpectralFilter, PolynomialFilter

x = np.random.randn(graph.N)

# Graph Fourier Transform and its inverse
coef = op.GFT(x)
assert np.allclose(op.inverseGFT(coef), x)

# Low-pass in the spectral domain: keep the 10 lowest graph frequencies
kernel = np.zeros(graph.N)
kernel[:10] = 1.0

sfilt = SpectralFilter(graph)
x_low = sfilt.apply(x, kernel)

# Same response, approximated by a degree-K polynomial of the shift operator
# (no eigendecomposition needed at apply time)
pfilt = PolynomialFilter(graph, order=12)
x_low_approx = pfilt.apply(x, kernel)

For directed operators the spectrum is complex. SpectralFilter.transform_in_real enforces conjugate symmetry on a kernel so the filtered signal stays real-valued, and phase_shift generalizes the Hilbert transform to arbitrary phase rotations in the GFT domain.

Surrogates and stationarity testing

from gyraph.surrogates import Surrogate

surr = Surrogate(graph)

# 200 surrogates preserving the directed spectral structure of x
surrogates = surr.directed_random_surrogate(x, nrands=200, seed=99)

# Test whether a set of realizations is stationary w.r.t. the graph
is_stat = surr.is_stationary(surrogates, eps_diag=0.5, eps_mean=0.5, verbose=True)

Measuring signal smoothness

from gyraph.utils import dirichlet, TV, directed_variation

graph.set_operator("laplacian")
print(dirichlet(x, graph.operator.M))        # x^T L x
print(TV(x, graph.adj_matrix, norm="L1"))    # ||x - Ax||_1
print(directed_variation(x, graph.adj_matrix))

Package layout

gyraph/
├── graphs/        Graph container, synthetic generators, mesh & physical-flow graphs
├── operators/     Adjacency, Laplacian, advection–diffusion, time–vertex operators;
│                  Jordan-block and zero-eigenvalue handling
├── filters/       Spectral, polynomial, Chebyshev, Faber, Hilbert, Tikhonov, Wiener
├── surrogates/    Surrogate generation and stationarity/PSD estimation
├── stats/         p-values, circular statistics, complex Gaussian sampling
└── utils/         Numerics, smoothness metrics, plotting, logging configuration

Every subpackage is re-exported at the top level, so import gyraph gives access to gyraph.graphs, gyraph.filters, gyraph.operators, gyraph.surrogates and gyraph.utils. Importing gyraph also applies a publication-oriented matplotlib style (science/ieee) — see gyraph/constants.py if you would rather keep your own rcParams.

Examples and data

Runnable scripts and notebooks live in examples/ — start with examples/basic/ for graph construction, filtering and visualization, then move to examples/advanced/.

The data/ directory ships the graph datasets used throughout the examples and tests:

• manhattan_graph_data/ — mid-Manhattan road network with NYC taxi flow signals
• usa_graph_data/ — US state adjacency graph with boundary shapefiles
• temperature_bretagne_graph_data/ — Brittany weather-station network

Development

pip install -e . && pip install pytest pytest-cov flake8 pre-commit && pre-commit install

Run the test suite (154 unit tests, ~84% line coverage):

python -m unittest discover -s tests/ -p 'test_*.py'

With coverage and linting, as CI does:

coverage run -m unittest discover -s tests/ -p 'test_*.py' && coverage report -m && flake8 . --max-line-length=127

Type checking is configured in mypy.ini. Both workflows — unit tests with a coverage badge, and packaging — run on every push to main (see .github/workflows/).

Contributions are welcome; please read CONTRIBUTING.md for the branch/commit conventions, NumPy-style docstring requirements and review process, and CODE_OF_CONDUCT.md before opening an issue or pull request.

Research powered by GyRAPH

GyRAPH is the reference implementation behind the following publications — the derivations, assumptions and validation for the code live there:

• Graph Diffusion-Advection Operator for Directed Graph Signal Processing — Chan, Cionca, Škultéty, Van De Ville. arXiv:2606.16306 → gyraph.operators.AdvectionDiffusion
• Graph Signal Surrogate Generation for Statistical Testing of Covariance Structure on Directed Graphs — Chan, Cionca, Van De Ville. arXiv:2608.01766 → gyraph.surrogates
• Hilbert Transform on Graphs: Let There Be Phase — Chan, Cionca, Van De Ville, IEEE Signal Processing Letters. IEEE Xplore → gyraph.filters.HilbertFilter

Citation

If you use GyRAPH in academic work, please cite it. Machine-readable metadata is in CITATION.cff:

@software{chan_gyraph,
  author  = {Chan, Chun Hei Michael},
  title   = {{GyRAPH}: Directed Graph Signal Processing Framework},
  url     = {https://github.com/miki998/GyRAPH},
  license = {MIT}
}

Acknowledgment

This project has been partly funded by the Swiss National Science Foundation under Sinergia grant 209470 “Precision mapping of electrical brain network dynamics with application to epilepsy”.

License

Released under the MIT License. Copyright © Chun Hei Michael Chan, MIP:Lab, EPFL.