scDisent

scDisent is the public code repository accompanying the manuscript scDisent: disentangled representation learning with causal structure for multi-omic single-cell analysis.

The model is designed for paired single-cell RNA-seq and ATAC-seq data. Instead of compressing both modalities into one entangled latent space, scDisent learns two coordinated branches:

• z_expr: expression-associated cell identity and state
• z_reg: regulation-associated variation

A sparse directed mapping from z_reg to z_expr makes the learned representation more interpretable and more suitable for perturbation-oriented analysis.

Repository Layout

scDisent/
|- configs/                   Hydra configuration files
|- scdisent/                   Core Python package
|  |- data/                   Data loading and preprocessing utilities
|  |- model/                  Encoders, decoders, disentanglement, causal map
|  |- training/               Losses and training loop
|  |- evaluation/             Metrics, discovery, validation, visualization
|  `- utils/                  Configuration and reproducibility helpers
`- scripts/
   |- preprocess/             Data download and preprocessing entry points
   |- train/                  Model training entry point
   |- eval/                   Benchmarking and analysis scripts
   `- baselines/              Baseline method wrappers

Installation

Python 3.10+ is recommended.

pip install -e .

For development tools:

pip install -e ".[dev]"

Data Preparation

The project targets paired multi-omic datasets stored as AnnData files.

To inspect supported public datasets:

python scripts/preprocess/download_data.py --list

To download and preprocess a benchmark dataset:

python scripts/preprocess/download_data.py --dataset pbmc_10k --preprocess
python scripts/preprocess/download_data.py --dataset human_brain_3k --preprocess
python scripts/preprocess/download_data.py --dataset mouse_brain_e18 --preprocess

Processed files are expected under data/processed/.

Training

The default configuration is defined in configs/default.yaml.

Train on PBMC with the default settings:

python scripts/train/train.py dataset=pbmc

Train on Human Brain or Mouse E18:

python scripts/train/train.py dataset=brain
python scripts/train/train.py dataset=e18

You can override any Hydra parameter from the command line, for example:

python scripts/train/train.py dataset=pbmc training.max_epochs=50 model.d_expr=64 model.d_reg=64

Evaluation

Evaluate a trained checkpoint:

python scripts/eval/evaluate.py --dataset pbmc
python scripts/eval/evaluate.py --dataset brain
python scripts/eval/evaluate.py --dataset e18

To run discovery-related analyses:

python scripts/eval/evaluate.py --dataset pbmc --discovery

License

MIT