Quickstart#

sctrial provides a streamlined, trial‑aware API for single‑cell clinical studies.

Minimal end‑to‑end example#

import sctrial as st

# 1. Define Design (two-arm trial)
design = st.TrialDesign(
    participant_col="pid",
    visit_col="visit",
    arm_col="arm",
    arm_treated="Treated",
    arm_control="Control",
    celltype_col="cell_type",
)

# For single-arm studies (e.g. vaccination, single-agent therapy):
# design = st.TrialDesign(
#     participant_col="pid",
#     visit_col="visit",
#     arm_col=None,  # No arm column needed
#     celltype_col="cell_type",
# )

# 2. Preprocess (add log1p‑CPM layer)
adata = st.add_log1p_cpm_layer(adata, counts_layer="counts")

# 3. Score Gene Sets (module scores)
gene_sets = {"Signature1": ["GENE1", "GENE2", "GENE3"]}
adata = st.score_gene_sets(
    adata,
    gene_sets,
    layer="log1p_cpm",
    method="zmean",
    prefix="ms_",
)

# 4. Run DiD
res = st.did_table(
    adata,
    features=["ms_Signature1"],
    design=design,
    visits=("V1", "V2"),
)

# 5. Summarize & visualize
print(st.summarize_did_results(res))
st.plot_did_forest(res)

Common add‑ons#

Fluent workflow API

# Chain common steps in a single workflow
res = (
    st.workflow(adata)
    .add_log1p_cpm_layer(counts_layer="counts")
    .score_gene_sets(gene_sets, layer="log1p_cpm", prefix="ms_")
    .did_table(features=["ms_Signature1"], design=design, visits=("V1", "V2"))
    .result()
)

Pairing diagnostics

# Count paired participants before longitudinal analysis
paired = st.count_paired(adata.obs, "visit", ["V1", "V2"], participant_col="pid")
print(paired)

AUCell scoring (optional)

# Requires: pip install pyscenic
adata = st.score_gene_sets_aucell(
    adata,
    gene_sets,
    layer="log1p_cpm",
    prefix="aucell_",
)

Cross‑sectional comparisons

cross = st.between_arm_comparison(
    adata,
    visit="V1",
    features=["ms_Signature1"],
    design=design,
    aggregate="participant_visit",
)

GSEA on DiD results

gsea = st.run_gsea_did(
    adata,
    gene_sets="KEGG_2021_Human",
    design=design,
    visits=("V1", "V2"),
)
st.plot_gsea_heatmap(gsea, fdr_thresh=0.25, top_n=20)

Pseudobulk export

pb = st.pseudobulk_export(
    adata,
    genes=["IFNG", "GZMB", "NKG7"],
    design=design,
    visits=("V1", "V2"),
    celltype_col="cell_type",
)

Next steps#