sclet: A State-Aware Single-Cell & Spatial Toolkit for SingleCellExperiment

sclet is a state-aware single-cell and spatial transcriptomics analysis toolkit built around SingleCellExperiment. It does not treat SCE as a low-level backend hidden behind another abstraction. Instead, it takes SCE as the primary analysis object and builds a unified Run*-style API around it, with Run<Mainline>Workflow() shells that tie independent modules into coherent, inspectable journeys.

The package introduces an explicit Analysis-State Contract. In practice, the object records what assay was used, which reduction was active, what clustering was chosen, and what downstream results were derived — as structured, queryable metadata rather than scattered ad hoc slots. This provenance backbone makes workflows reproducible by default and ready for downstream AI-assisted reasoning.

Key integration pattern: Python backends (scVI, scVelo, CellRank, SCENIC, cell2location, CellOracle) are all isolated via basilisk and exposed as plain R functions. No manual conda configuration. The function signature is always Run*(sce, ...); the return value is always an SCE with the analysis state updated.

Analysis Mainlines

The package is organized around 11 user-facing mainlines, each answering a concrete question in a single-cell or spatial project.

1. Data ingress & interoperability — Read10X(), ReadH5AD(), ConvertToAnnData(). Move between SCE, Seurat, and AnnData without losing the object story.
2. Core single-cell workflow — RunQC(), RunNormalization(), RunHVG(), RunPCA(), RunTSNE(), RunUMAP(), RunClustering(). QC through clustering in one coherent pipeline.
3. Integration & batch correction — RunIntegration(method = c("Harmony", "scVI")). Align multi-sample data into a reusable corrected view.
4. Cell identity & reference mapping — RunReferenceMapping(), RunSingleR(), RunKNNPredict(), RunSymphony(). Annotate cells through multiple backends with confidence inspection.
5. Cell fate & dynamic processes — RunDiffusionMap(), RunSlingshot(), RunVelocity(), RunCellRank(). Trajectory, RNA velocity, and fate probability in one dynamics route.
6. Program, regulon & mechanistic interpretation — RunAUCell(), RunGSVA(), RunUCell(), RunSCENIC(). From gene-set scoring to full regulon activity networks.
7. Differential analysis & functional interpretation — RunDEtest(), RunPseudobulkDE(), RunEnrichment(). Marker discovery, pseudobulk testing, and enrichment in one chain.
8. Cell-cell communication & microenvironment — RunCCI(method = c("CellChat", "CellPhoneDB", "NicheNet")). Ligand-receptor signaling with multiple backend adapters.
9. State priority & perturbation sensitivity — RunAugur(), RunRareCellDetection(method = "density"). Prioritize perturbation-sensitive or rare cell states with SCE-native algorithms.
10. Spatial context & niche analysis — RunSpatialDeconvolution(), RunSpatialColocalization(), RunSpatialNiche(). Spatial deconvolution (cell2location), colocalization (SVP GLOBALBV), and niche detection (SVP LISA).
11. Multimodal expansion — reserved documentation path for future ADT / ATAC / multiome support.

Documentation

The online book follows the same 11-mainline structure, organized into three parts:

• Part I — How sclet Thinks (2 chapters): the state contract and provenance-aware automation.
• Part II — From Data to Discovery (11 chapters): one chapter per analysis mainline, ordered to match a real project journey.
• Part III — Specialized Techniques (8 chapters): visualization, metacells (SuperCell), differential abundance (Milo), phenotype association (scPAS), interactive exploration (iSEE), spatial variance (SVP), and AI-assisted analysis.

All mainline code chunks in the book are CI-verified: they run inside GitHub Actions on every push to the docs or devel branch. The book acts as both a tutorial and a lightweight regression test suite for the package. Pre-prepared demo data (PBMC, Hermann spermatogenesis, DLPFC Visium, SCENIC references) is generated from Bioconductor data packages and cached during the CI build.

✍️ Authors

Guangchuang YU

School of Basic Medical Sciences, Southern Medical University

https://yulab-smu.top

⏬ Installation

Get the development version from github:

## install.packages("remotes")
remotes::install_github("YuLab-SMU/sclet")

📖 Vignette

For more details, please refer to the online documents:

• vignette