IggyTop: Immunological Graph Yielding Top receptor-epitope pairings

This repository uses the BioCypher framework to harmonize databases with existing immunoreceptor-epitope matching information. The aggregated data is provided in tabular and graph formats.

BioCypher provides a modular architecture where each data source is processed through dedicated transformation scripts called adapters. These adapters are the interface between raw data sources and the IggyTop dataset. We use tidytcells to standardize gene names, cdr3 sequences and junction sequences for both BCR and TCR datasets. We aim to follow AIRR and IMGT standards. This project provides adapters for the following databases:

• IEDB
• VDJdb
• McPAS-TCR
• CEDAR
• ITRAP (data filtered from 10X Genomics Dataset)
• TRAIT
• TCR3d
• NeoTCR
• BATCAVE

The aggregated data from all adapters is available in the (bimonthly) releases. These releases are used by Scirpy, which provides a simple interface to access the data in anndata format. You can also rebuild the DB using the provided code with custom parameters. On a consumer laptop, building the full DB typically takes 20-30 minutes.

The full documentation is available online via Read the Docs.

Graphs vs. Tables

Two paths are covered: A tabular path that stacks source databases into a large table (used in Scirpy and Releases), and a knowledge graph path that converts the source data into a graph. Both are documented in the documentation. For details, see Graph Data Structure and Tabular Data Structure.

Quick start: Tabular data (Scirpy)

To use the database in Python, install Scirpy (>=v0.24.0). Then use this function to load the dataset in anndata (tabular) format:

import scirpy as ir

iggytop = ir.datasets.iggytop(deduplicated=True, tag='latest')

# Or (e.g. for VDJdb only)
vdjdb = scirpy.datasets.vdjdb(tag='latest')

Prerequisites

• uv: dependency management, required to run DB/graph generation locally.
• docker: run containers, required to run Neo4j container for inteactive graph queries.

Knowledge graph in Neo4j (Docker image)

Every data release ships a ready-to-run Docker image, ghcr.io/biocypher/iggytop-neo4j: a Neo4j instance with the full IggyTop knowledge graph built in. You only need Docker. There's no need to clone the repo, install Python, or build anything.

docker run -d --name iggytop \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/neo4jpassword \
  -v iggytop_data:/data \
  ghcr.io/biocypher/iggytop-neo4j:latest

Image tags: latest points to the latest data release. Every release is also available under its own tag (e.g. data-2026.08.03.063907, see the package page), so you can pin the exact data version you used.

Querying the graph

• Browser: open http://localhost:7474 and log in with neo4j / neo4jpassword (change it via NEO4J_AUTH or in docker-variables.env).

In the browser, you can now run queries against the database — the full graph has over a million nodes, so scope exploratory queries with a LIMIT, e.g.:

MATCH (n) RETURN n LIMIT 100

To get a feel for the schema, a good starting point is to expand outward from a single Binding node — the central node type linking a TCR/BCR receptor to the epitope it binds — and follow its relationships a few hops out:

MATCH path = (n:Binding)-[*1..4]->(m) WHERE n.complete = true RETURN path LIMIT 16

For more information on the Graph schema, check out Graph Data Structure. The result should look similar to this:

You can adapt color, size and labels of the nodes in the control panel on the right.

Local Installation

1. Clone the repository:

   git clone https://github.com/biocypher/iggytop.git
   cd iggytop

2. Install dependencies using uv:

   # Core installation (includes dev dependencies)
   uv sync
   
   # Include documentation and Jupyter tools
   uv sync --group docs

3. You are ready to go!

   uv run create_knowledge_graph.py

   or

   uv run create_release.py

More information can be found in the documentation.

Pipeline

• create_release.py: builds every selected adapter's source table exactly once, then emits the raw merged dataset, the filtered+deduplicated dataset (in anndata/ AIRR JSON format, for integration into Scirpy), and the neo4j knowledge graph files from that same run, avoiding rebuilding the tables multiple times. Each output can be toggled independently:

uv run create_release.py --adapters VDJDB CEDAR --filter-10x

--filter-10x only affects the deduplicated dataset. Use --not_merged, --not_deduplicate or --not_graph to skip any of the three outputs, and --graph-output-format to choose the graph's BioCypher output format (default neo4j).

• create_knowledge_graph.py: a standalone, graph-only entrypoint into io.create_knowledge_graph(), useful when you don't need the AnnData/AIRR outputs. Use the --adapters flag to select specific source databases and --output-format to choose the output (neo4j, networkx or airr; default neo4j):

uv run create_knowledge_graph.py --adapters VDJDB CEDAR --output-format networkx

• src/iggytop/adapters contains modules that define each data source adapter.

• src/iggytop/config/schema_config.yaml: defines the schema of the knowledge graph. It is used by BioCypher to map the data source to the knowledge representation based on ontology (see this part of the BioCypher tutorial).

• src/iggytop/config/biocypher_config.yaml: defines BioCypher parameters such as the mode, separators, and other options. More on its use can be found in the documentation.

Releases, Testing and CI/CD

IggyTop uses GitHub Actions to automate bimonthly data releases and ensure data integrity through continuous integration. Each release is built by create_release.py and covers both the tabular datasets and the knowledge graph. Check out the latest release here.

Bimonthly Data Releases

Find the releases here

• Frequency: Automated releases on the 1st day of every 2nd month (first scheduled on May 1, 2026).
• Release Assets: the merged and deduplicated datasets (AnnData / AIRR JSON) and knowledge_graph.tar.gz (neo4j-admin import files). Check out the release notes for more information on the released datasets.
• Docker image: every release also publishes ghcr.io/biocypher/iggytop-neo4j, a Neo4j image with that release's knowledge graph built in, tagged with the release tag (latest follows the latest release). See Knowledge graph in Neo4j (Docker image).

Automated Testing

Before any data is released, the CI pipeline (based on GitHub Actions) runs a validation suite to catch breaking changes in upstream databases.

How to run tests locally:

# Install all dependencies (including docs for notebook testing)
uv sync --all-groups

# Install Jupyter kernel for notebook execution (one-time setup)
uv run python -m ipykernel install --user --name python3

# Run all tests (including notebook validation)
uv run pytest tests/

Why the kernel installation? The test suite includes validation of Jupyter notebooks (tutorials and database summaries) to ensure they execute without errors. This requires a Jupyter kernel registered with the name "python3" to match the notebooks' configuration. The installation is a one-time setup per environment.

How to test the CI pipelines Ensure you have Docker and act installed, then run:

# Run the workflow
act workflow_dispatch -W .github/workflows/ci_ingestion.yml

Related work

If you find a dataset (e.g. training data for a model) and would like to find the source of the records using the IggyTop dataset, check out this tool.

This project is built on (and part of) the BioCypher framework. Make sure to check out this cool project!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or create an Issue if you discover any problems.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use IggyTop in your research, please cite it using the following DOI:

You can find the full citation details on the Zenodo page.

We also provide a CITATION.cff file for customized citations.