prism-de 0.1.0

PRISM: Probabilistic Inference of Subject-level Mixture for contextualized differential expression

PRISM

Phenotype-Resolved Inference in Single-Cell Mixed Models via Latent Disease States and Contextualized Differential Expression

▶ Full model explainer (1080p, ~1 min)

Overview

PRISM extends the NEBULA negative-binomial log-normal mixed model for single-cell differential expression by introducing:

1. Latent per-cell disease states $d_{ij} \sim \text{Bernoulli}(\rho_i)$ that separate truly affected cells from unaffected ones within disease subjects.
2. Contextualized covariate effects $x^\top \Gamma_g z$ that model how context modulates all covariate effects (a main effect of context on expression).
3. Context-dependent disease effects $\Delta_g(z) = \alpha_g + \theta_g^\top z$ that let the DE magnitude vary with continuous cell-level covariates ($\alpha_g$ = constant disease effect, $\theta_g$ = context modulation).
4. An EM algorithm that alternates between inferring $q_{ij} = P(d_{ij}=1 \mid Y, \Theta)$ (E-step) and optimizing the NEBULA-LN approximate likelihood weighted by $q_{ij}$ (M-step).

Installation

Option A — conda (recommended)

git clone https://github.com/AndreaRubbi/ContextualizedDifferentialExpression.git && cd ContextualizedDifferentialExpression
conda env create -f environment.yml
conda activate prism
pip install -e .

Option B — pip + venv

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# If CUDA 12.4 driver, pin a compatible torch build:
pip install torch==2.5.1+cu124 --index-url https://download.pytorch.org/whl/cu124

# Required for HVG selection (seurat_v3 flavor):
pip install scikit-misc

Verify

python -c "
import torch, prism
print(f'PRISM v{prism.__version__}')
print(f'PyTorch {torch.__version__}, CUDA available: {torch.cuda.is_available()}')
"

Quick start

from prism.data.simulation import generate_prism_data
from prism.inference.em_loop import PRISMConfig, PRISMTrainer

# 1. Generate synthetic data: 50 subjects × 200 cells × 60 genes
data, ground_truth = generate_prism_data(
    n_subjects=50, n_genes=60, n_cells_per_subject=200,
    rho=0.6, seed=42, device="cpu",
)

# 2. Configure and fit
config = PRISMConfig(
    n_genes=data.n_genes,
    n_covars=data.n_covars,
    n_context=data.n_context,
    max_em_iter=30,
    m_step_optimizer="trust_region",
    run_wald=True,
    wandb_enabled=False,
    device="cpu",
)
trainer = PRISMTrainer(config)
results = trainer.fit(data)

# 3. Inspect results
print(f"EM iterations: {results.em_iterations}")
print(f"Converged: {results.converged}")
sig = results.significant_genes(fdr=0.05)
print(f"Significant genes (FDR<0.05): {sig.sum().item()}")

Project layout

prism/
├── prism/
│   ├── model/           # PrismModel, encoders, NB/HL likelihoods
│   ├── inference/       # EM (e_step, m_step, em_loop), Wald & score tests
│   ├── data/            # PrismData, simulation, ROSMAP preprocessing
│   ├── baselines/       # NEBULA, context-only, latent-only, stratified
│   ├── evaluation/      # Metrics and plotting
│   └── utils/           # Numerical helpers, logging
├── tests/               # Unit and integration tests
└── tutorials/           # Notebook tutorials (API, synthetic, ROSMAP)

Tutorials

• tutorials/getting_started.ipynb — end-to-end API walkthrough on simulated data (fit, test, interpret).
• tutorials/synthetic_data_tutorial.ipynb — generate data, sweep parameters, plot FPR/power.
• tutorials/rosmap_real_data.ipynb — applying PRISM to ROSMAP microglia.
• docs/TUTORIAL.md — installation + CLI reference.

Reproducing the paper

All scripts, pipelines and notebooks that reproduce the paper's results live in the top-level reproducibility/ folder (Snakemake ablations, NEBULA-style benchmark, external baselines, ROSMAP and COVID real-data analyses). See ../reproducibility/README.md.

Citation

@article{prism2026,
  title={PRISM: Phenotype-Resolved Inference in Single-Cell Mixed Models
         via Latent Disease States and Contextualized Differential Expression},
  author={Anonymous Authors},
  journal={Under review},
  year={2026}
}

Regenerating the animations

The animated visuals are built with Manim Community.

pip install manim
cd media

# Standalone logo (1080p MP4)
manim -qh prism_explainer.py PRISMLogo

# Full explainer (1080p MP4)
manim -qh prism_explainer.py PRISMExplainer

# Full explainer (720p GIF — large file)
manim -qm --format=gif prism_explainer.py PRISMExplainer