Design-Aware Participant-Level Inference for Longitudinal Single-Cell Studies
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
| Feature | Description |
|---|---|
| Trial-Aware Design | Define participant, visit, arm, and cell type columns once |
| Robust Statistics | Wild cluster bootstrap, participant-level aggregation |
| Multiple Comparisons | Built-in FDR correction across features and cell types |
| Power Analysis | Two-arm DiD and single-arm paired power/sample size calculations |
| Single-Arm Support | arm_col=None for studies without a control arm |
| Publication-Ready Plots | Forest plots, interaction plots, GSEA heatmaps |
| Scalable | Efficient processing of large single-cell datasets |
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:
| Design | Description | Dataset | Source | Tutorial |
|---|---|---|---|---|
| Two-arm paired DiD | Pre/post × treatment/control interaction | Sade-Feldman et al., Cell 2018 — melanoma immunotherapy | GSE120575 | Immunotherapy |
| Two-arm paired DiD | Pre/post × treatment/control interaction | Zhang et al., Cell 2021 — TNBC immunotherapy (anti-PD-L1+Chemo vs Chemo) | GSE169246 | TNBC |
| Single-arm pre/post | Paired within-arm contrasts over time | ImmPort GSE171964 — PBMC vaccine response | GSE171964 | Vaccine |
| Single-arm pre/post | Paired within-arm, multi-timepoint | van Galen et al., Cell 2019 — AML chemotherapy | GSE116256 | — |
| Single-arm multi-timepoint | Longitudinal tracking across 4 visits | GSE290722 — CAR-T cell therapy (ZUMA-1) | GSE290722 | — |
| Cross-sectional between-arm | Between-group comparison at one timepoint | Stephenson et al., Nature Medicine 2021 — COVID-19 severity | E-MTAB-10026 | COVID-19 |
Additional tutorial: Scalability Benchmark — performance testing on the Sade-Feldman dataset.
Documentation
Full documentation: https://www.omar-lab.com/sctrial/
Citation
If you use sctrial in your research, please cite:
Vasanthakumari P, Valencia I, Aghmiouni MR, Magana B, Omar M. sctrial: Participant-Level Differential Analysis for Longitudinal Single-Cell Experiments. bioRxiv 2026. doi:10.64898/2026.04.02.716219.
@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},
journal = {bioRxiv},
year = {2026},
doi = {10.64898/2026.04.02.716219},
url = {https://www.biorxiv.org/content/10.64898/2026.04.02.716219v1}
}
License
MIT License - see LICENSE for details.
Metadata
Release files for sctrial 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sctrial-1.0.0.tar.gz | 14.8 MB | Without provenance | Details for sctrial-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sctrial-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for sctrial-1.0.0-py3-none-any.whl |
Total release size: 15.1 MB
Release files / sctrial-1.0.0.tar.gz
| Download URL | sctrial-1.0.0.tar.gz |
|---|---|
| Size | 14.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
49c1c1a004c2b33eaf360b60a9077824f053b03e381e6b3c8dcde028a52e1fef
|
|
BLAKE2b-256 checksum How to use checksums |
d5bf1feb1d616cd259a2c5d00c413350803ded1518380ee982f0d83649ba2639
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Release files / sctrial-1.0.0-py3-none-any.whl
| Download URL | sctrial-1.0.0-py3-none-any.whl |
|---|---|
| Size | 273.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3116837efeffe371a1cbf1a20f7856cd53e14cfe8db89ba5b88c2415b2b89d90
|
|
BLAKE2b-256 checksum How to use checksums |
4b594ab1893879e79b203c30e103a740e40b2f69a8851a3e8be48044d3548964
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.13
|
Security for sctrial 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.