regstatusnet 1.0.0

Per-cell TF activity inference with learned post-translational regulation detection from scRNA-seq

RegStatusNet

GRN-constrained structured latent space for per-cell transcription factor activity inference — with learned post-translational regulation detection

---

What it does

RegStatusNet infers per-cell transcription factor (TF) activity from scRNA-seq data alone. Unlike linear methods (VIPER, decoupleR), it:

• Assigns each latent dimension to a named TF (not an abstract factor)
• Enforces activator/repressor sign polarity from DoRothEA as a hard architectural constraint
• Learns a per-TF parameter α that identifies which TFs are post-translationally regulated — without any PTM supervision
• Scales to 100k+ cells with adversarial batch correction

Key result: α correctly assigns low values to 14/16 known PTM regulators (87.5% recall), including the NF-κB, JAK-STAT, FOXO, and TGF-β/SMAD families, independently confirmed by ATAC chromatin concordance (Spearman ρ=+0.468, p=5.3×10⁻³).

---

Quickstart (3 lines)

import regstatusnet as rsn

model = rsn.Predictor.from_pretrained("pbmc_multiome_v1")   # downloads ~200 MB from Zenodo
z = model.transform(adata)                                   # (cells, 91) TF activity matrix

The pretrained PBMC model (pbmc_multiome_v1) is hosted at Zenodo: DOI: 10.5281/zenodo.20470333

---

Installation

git clone https://github.com/JiaenLin/RegStatusNet.git
cd RegStatusNet
pip install -e ".[bio]"

Or for inference only (no training dependencies):

pip install torch scanpy anndata decoupler

---

Full API

from predictor import Predictor

# Load from Zenodo (auto-downloads on first call)
model = Predictor.from_pretrained("pbmc_multiome_v1")

# Or from a local checkpoint
model = Predictor.from_pretrained("runs/stage2_multiome/best_model.pt")

# Run inference — auto gene alignment, handles missing genes
z = model.transform(adata, batch_size=512)       # (cells, 91) numpy array

# With uncertainty and α
out = model.transform(adata, return_dict=True)
# out["z"]      — (cells, 91) TF activity
# out["logvar"] — (cells, 91) uncertainty (log-variance)
# out["alpha"]  — (91,) per-TF α values (model property, not cell-specific)

# Interpret α
print(model.alpha_table())           # DataFrame: TF, alpha, tier
print(model.tf_names[:5])            # ['AR', 'ATF1', 'ATF2', ...]

---

Pretrained model: pbmc_multiome_v1

Property	Value
Training data	PBMC 10k Multiome (10x Genomics)
Cells	11,620
Cell types	17 (CellTypist Immune_All_Low)
TFs	91 (DoRothEA AB confidence)
GRN edges	3,373 (95.4% activating)
Input genes	3,257 (3,000 HVGs + 257 forced TF genes)

Validated benchmarks:

• DoRothEA+viper: 78% of TFs r > 0.5, mean r = +0.641 (+0.44 above null)
• Perturb-seq specificity: top-5 hit rate 16.5% vs 5.5% chance (p=1.3×10⁻⁴)
• PTM recall: 87.5% (14/16 known PTM regulators assigned α < 0.05)
• ATAC chromatin validation: Spearman(α, ρ_atac) = +0.468, p=5.3×10⁻³

---

Use cases

Notebook	Description
docs/use_cases/pbmc_example.ipynb	Quickstart: load model, run inference, visualise
docs/use_cases/uc2_ifn_stimulation.ipynb	Apply to IFN-β stimulation data (Kang 2018)
docs/use_cases/uc3_ptm_discovery.ipynb	Discover PTM-regulated TFs in your own PBMC data

---

Train on your own data

See docs/extending_to_new_tissues.md for a step-by-step guide.

Quick overview:

# 1. Prepare data
python scripts/prepare_stage2_data.py --h5ad your_data.h5ad --out_dir data/

# 2. Train
python tests/train_stage2.py --config configs/stage2_multiome.yaml \
    --h5ad data/your_data_processed.h5ad

# 3. Validate
python scripts/run_viper.py \
    --ckpt runs/your_run/best_model.pt \
    --h5ad data/your_data_processed.h5ad

---

Reproduce paper figures

# Generate Figures 2–5 (requires Stage 4 analysis CSVs from HPC)
bash scripts/make_figures.sh

# Generate Supplementary Figures S1–S2 (self-contained, no data needed)
python scripts/plot_supplementary.py --out_dir figures

# Generate Figure 1 UMAP (requires checkpoint + h5ad)
python scripts/plot_figure1_umap.py \
    --ckpt runs/stage2_multiome/best_model.pt \
    --h5ad data/pbmc10k_multiome.h5ad

# Generate Figure 1 A–C schematic (PowerPoint)
python scripts/make_figure1_schematic.py

---

Docker

# Build image
docker-compose build

# CPU inference — mount your h5ad at /data and run a script
docker-compose run \
  -v /path/to/your/data:/data \
  regstatusnet python -c "
import regstatusnet as rsn
import scanpy as sc
adata = sc.read_h5ad('/data/your_pbmc.h5ad')
model = rsn.Predictor.from_pretrained('pbmc_multiome_v1')
z = model.transform(adata)
print('z shape:', z.shape)
"

# GPU inference — requires nvidia-container-toolkit
docker-compose run \
  -v /path/to/your/data:/data \
  regstatusnet-gpu python your_script.py

# Jupyter Lab (CPU) — open http://localhost:8888 after running
docker-compose up notebook

Environment variables (see .env.example):

• REGSTATUSNET_CACHE — override checkpoint cache directory
• REGSTATUSNET_REF_H5AD — path to reference h5ad (locally-trained models only)

Security note: The notebook service disables the Jupyter token for ease of use. This is safe for local development but do not expose port 8888 on a public network.

---

Citation

If you use RegStatusNet, please cite:

@article{lin2026regstatusnet,
  title   = {A GRN-constrained structured latent space identifies post-translationally
             regulated transcription factors from single-cell RNA sequencing},
  author  = {Lin, Jiaen},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.5281/zenodo.20470333}
}

---

License

MIT © 2026 Lin Jiaen