scHiCGNN

scHiCGNN is a CLI-first Python toolkit for learning cell embeddings from single-cell Hi-C contact matrices. It converts per-cell chromosome contact maps into graphs, trains graph neural networks for cell representation learning, and ships a PCA baseline plus downstream inspection, clustering, and explainability workflows. The repository accompanies the scHi-C GNN research project and is organized for reproducible, config-driven runs.

Overview

scHi-C GNN supports supervised GNN training, YAML-driven preprocessing, cached feature/graph materialization, a PCA baseline, and clustering analysis.

scHi-C matrices
    -> preprocessing / normalisation
    -> chromosome graphs
    -> GNN chromosome encoder
    -> cell embedding
    -> clustering / inspection / explainability

Quick Start

Install the package in editable mode:

uv pip install -e .

Precompute cached graph-building artifacts for the Ramani profile:

schicgnn-precompute configs/train/Ramani.yaml

Train the default Ramani model:

schicgnn-train configs/train/Ramani.yaml

Inspect the newest embedding artifact written by that run:

EMB="$(find gnn_results/Ramani -name '*_embeddings.pkl' | sort | tail -n 1)"
python scripts/inspect_embeddings.py "$EMB" --head 5

For held-out clustering, set output.embedding_mode: test_only or full in a copy of the training YAML before running schicgnn-train, then pass the generated *_test.pkl file to schicgnn-cluster.

Supported Datasets

Dataset	Species	Recommended Genome Build	Cell Types
Ramani	Human	hg19	4 cell types
Collombet	Mouse	mm10	5 cell types
Flyamer_merged	Mouse	mm9	3 cell types
Nagano	Mouse	mm9	5 cell-cycle phases from metadata
4DN	Human	hg19	Auto-discovered from folder names
Lee	Human	hg19	Auto-discovered from folder names

Supported genome references are hg19, hg38, mm9, and mm10. Dataset names are case-sensitive and must match the directory names under ../data/.

CLI Commands

Installed commands:

Command	Purpose
schicgnn-precompute	Cache node features and optional chromosome graphs from a training YAML
schicgnn-train	Train a GNN model from a training YAML and write embeddings/checkpoints
schicgnn-pca	Run the PCA baseline from a PCA YAML
schicgnn-cluster	Cluster one embedding artifact using a clustering YAML
python scripts/inspect_embeddings.py	Inspect or compare saved embedding pickle files
schicgnn-explain	Extract gradient saliency and attention-based explanations from a trained checkpoint

Developer and thesis utilities available through python -m:

Module	Purpose
python -m schicgnn.cli.graph_profile	Profile graph sparsity, topology, and node features from a training YAML
python -m schicgnn.cli.topk.analyze	Measure graph statistics across candidate topk values
python -m schicgnn.cli.topk.sweep	Run repeated training across topk and seed combinations
python -m schicgnn.cli.topk.report	Summarize top-k graph and training artifacts into a report

Documentation

• docs/INSTALL.md: installation, optional extras, GPU notes, and troubleshooting.
• docs/REPRODUCING.md: end-to-end reproduction workflows for the main experiments.
• docs/CLI_REFERENCE.md: command reference for all installed and module-invoked CLIs.
• docs/ARCHITECTURE.md: method overview, package structure, file formats, and Python API entry points.
• docs/PUBLIC_API.md: stable importable surface of the schicgnn package, library-mode quickstart, and stability guarantees.
• docs/GENOME_BUILDS.md: genome-build guidance and dataset-specific reference choices.
• docs/NAGANO_LABEL_FIX.md: Nagano-specific labeling details and metadata handling.
• configs/train/CONFIG_REFERENCE.md: training and precompute YAML schema.
• configs/pca/CONFIG_REFERENCE.md: PCA YAML schema.
• tests/README.md: test suite layout and pytest usage.
• scripts/README.md: maintained analysis scripts used for reporting and diagnostics.

License

MIT.