Absynthe — Synthetic Graph Dataset Framework

Absynthe is a Python framework for generating synthetic graphs out of configurable motifs, composing them with several composition patterns, labeling the result via subgraph isomorphism, applying reversible perturbations, and producing reproducible datasets for graph-learning experiments. It can also build datasets from existing graph collections by ingesting graphs from a folder (GraphML or RDF).

Features

• Reusable motif generators — cycle, house, chain, star, gate (see motifs/ and the registry in motifs/init.py).
• Composition patterns — sequential, ER, BA, SBM, star, hierarchical — via graph/composition_engine.py.
• Random per-graph motif counts using IntDistribution (uniform / normal / poisson) in utils/distributions.py.
• Flexible labeling: per-node, per-edge, per-graph, or custom combinations via pluggable LabelingFunction in graph/labeling_functions.py and interfaces/labeling_function.py.
• Reversible perturbations — node removal with six strategies (random, degree, motif, core, periphery, centrality), edge removal, edge rewiring — in graph/perturbations.py and graph/perturbation_strategies.py, plus reconstruction in graph/reconstruction.py.
• Folder / RDF graph ingestion via graph/folder_graph_generator.py — supports .graphml, .rdf, .ttl, .nt, .n3, .owl.
• Optional FastAPI + React web interface for interactive exploration (see web/).

Requirements

• Python 3.8 or newer.
• A virtual environment is recommended (example below).
• Core dependencies are listed in requirements.txt (networkx, matplotlib, lxml, rdflib).
• Web-interface dependencies are listed in requirements-web.txt.

Installation

# Windows (PowerShell)
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

# macOS / Linux (bash)
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Quick start — generating a dataset

The canonical end-to-end driver is gen_dataset.py. After activating the venv and installing requirements.txt:

python gen_dataset.py

This produces four bundled datasets under datasets/:

• datasets/house/
• datasets/cycle_5/
• datasets/star_5/
• datasets/house_cycle5_star5/

Each dataset contains the perturbed graph variants (organized by perturbation type) along with metadata describing the motifs, labels and the reversible perturbation hints.

Reproducibility is controlled by a single global seed set through utils.rng.set_seed(...) (see utils/rng.py) at the top of gen_dataset.py. Change that value to obtain different random instances.

Reproducible runs via JSON config

The same configuration can be expressed in a JSON file and passed to the script, so an experiment can be reproduced from a single artifact:

python gen_dataset.py configs/default.json   # explicit path
python gen_dataset.py --json                 # shorthand for configs/default.json
python gen_dataset.py                        # no args → in-script DATASET_CONFIGS

The JSON describes a suite of datasets sharing a shared block of defaults (seed, perturbations, labeling, generation parameters) which each entry in datasets[] can selectively override. The schema mirrors the DatasetGenerateRequest model used by the web backend (web/backend/models/dataset_models.py), so a config produced from the GUI is interchangeable with one generated by hand. See configs/default.json for a working template that reproduces the four bundled datasets above.

For shorter, narrative examples that walk through individual building blocks (single-graph composition, distributions, composition patterns), see test_graph.py and prueba.py.

For the full API walkthrough — motif tables, composition parameters, custom labelers and custom motifs — see the companion guide Absynthe_GUIDE.md.

Project structure

• graph/ — composite generators, composition engine, dataset orchestrator, labeling functions, perturbations and strategies, reconstruction, folder/RDF loader.
• motifs/ — built-in motif generators and the registry in motifs/init.py.
• interfaces/ — abstract base classes (GraphGenerator, MotifGenerator, LabelingFunction, Perturbation) and data models (LabelingResult, PerturbationHint).
• utils/ — global RNG (utils/rng.py), IntDistribution (utils/distributions.py), graph helpers.
• web/ — FastAPI backend + React/TypeScript frontend.
• Root scripts: gen_dataset.py, test_graph.py, prueba.py, test_dataset.py, test_reconstruction.py, visualize.py, visualize_graph_dataset.py.
• Companion docs: Absynthe_GUIDE.md.

Web interface

Development (two terminals)

Terminal 1 — backend (from project root):

pip install -r requirements-web.txt
uvicorn web.backend.app:app --reload --port 8000

Terminal 2 — frontend:

cd web/frontend
npm install
npm run dev          # → http://localhost:5173

Production (single command)

pip install -r requirements-web.txt
python -m web        # builds the frontend (if needed) and serves the SPA + API at :8000

The python -m web entry point is implemented in web/main.py and accepts --host, --port, --reload and --build flags.

Docker

docker compose up    # → http://localhost:8000

See docker-compose.yml and Dockerfile for the build configuration.

License

This repository is licensed under the GNU General Public License v3.0 (GPL-3.0). See the GPL-3.0 license file in the project root for the full text.