Skip to main content

sctrial

Design-Aware Participant-Level Inference for Longitudinal Single-Cell Studies

Test Status Release Version Python Versions PyPI Downloads Documentation


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

sctrial overview — from scRNA-seq input through trial-aware analysis to statistical outputs

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)

Source distribution for sctrial 1.0.0
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)

Table of built distributions (wheels) for sctrial 1.0.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page