sctrial 0.3.3

Participant-Level Differential Analysis for Longitudinal Single-Cell Experiments

Overview

sctrial is a Python package for participant-level differential analysis of longitudinal single-cell RNA-seq data from clinical trials and translational studies. Built on AnnData and the scverse ecosystem, it provides:

• Difference-in-Differences (DiD) analysis with participant fixed effects
• Paired within-arm pre→post contrasts
• Between-arm comparisons at fixed timepoints
• Cell-type abundance change testing
• Gene set enrichment analysis (GSEA) on DiD rankings
• Power analysis and sample size calculations
• Effect size estimation with confidence intervals

Key Features

Installation

pip install sctrial

For development:

git clone https://github.com/TheOmarLab/sctrial.git
cd sctrial
pip install -e ".[dev]"

Quick Start

pip install "sctrial[plots]"   # includes dataset loaders and visualization

import sctrial as st

# 1. Load a real immunotherapy trial dataset (auto-downloads on first use)
adata = st.load_sade_feldman()
adata = st.harmonize_response(adata)  # majority-vote response labels

# 2. Define trial design
design = st.TrialDesign(
    participant_col="participant_id",
    visit_col="visit",
    arm_col="response_harmonized",
    arm_treated="Responder",
    arm_control="Non-responder",
    celltype_col="cell_type",
)

# 3. Score gene sets (dataset ships pre-normalized with log1p_tpm layer)
gene_sets = {
    "Cytotoxicity": ["GZMA", "GZMB", "PRF1", "GNLY", "NKG7"],
    "Exhaustion":   ["PDCD1", "CTLA4", "HAVCR2", "LAG3", "TIGIT"],
}
adata = st.score_gene_sets(adata, gene_sets, layer="log1p_tpm", method="zmean", prefix="ms_")

# 4. Run Difference-in-Differences on CD8 T cells
features = [c for c in adata.obs.columns if c.startswith("ms_")]
results = st.did_table(adata, features, design, visits=("Pre", "Post"), celltype="CD8 T cell")
print(results[["feature", "beta_DiD", "se_DiD", "p_DiD", "FDR_DiD"]])

Or use the one-liner convenience wrapper for a quick multi-cell-type scan:

results = st.quick_did(
    adata,
    module_scores=gene_sets,
    visits=("Pre", "Post"),
    arm_col="response_harmonized",
    arm_treated="Responder",
    arm_control="Non-responder",
    celltype_col="cell_type",
)

Supported Study Designs & Datasets

sctrial ships with five real clinical trial datasets, accessible via built-in loaders (st.load_*()). Each demonstrates a different study design:

Additional tutorial: Scalability Benchmark — performance testing on the Sade-Feldman dataset.

Documentation

Full documentation: https://www.omar-lab.com/sctrial/

• API Reference
• Tutorials
• FAQ

Citation

If you use sctrial in your research, please cite:

Vasanthakumari P, Valencia I, Aghmiouni MR, Magana B, Omar MN. sctrial: Participant-Level Differential Analysis for Longitudinal Single-Cell Experiments. bioRxiv (2026).

@article{vasanthakumari2026sctrial,
  title = {sctrial: Participant-Level Differential Analysis for Longitudinal Single-Cell Experiments},
  author = {Vasanthakumari, Priyanka and Valencia, Itzel and Aghmiouni, Maryam R. and Magana, Bryan and Omar, Mohamed N.},
  journal = {bioRxiv},
  year = {2026},
  url = {https://github.com/TheOmarLab/sctrial}
}

License

MIT License - see LICENSE for details.