How gao-lab/slat works
1. Top-level shape
- This repository is split into one core Python library, scSLAT, plus several “application” areas: benchmark, evaluation, case, docs, data, and env.
- The architecture is not a web service; it is a research/analysis codebase centered on a single alignment model and a set of reproducible pipelines around it.
2. Core package: scSLAT/
- scSLAT is the main runtime package published to PyPI.
- It provides the SLAT model implementation, training/inference utilities, metrics, and visualization helpers.
- This is the boundary that downstream notebooks and workflows import from; everything else in the repo is largely orchestration, experimentation, or documentation.
3. Modeling subsystem: scSLAT/model/
- graphmodel.py, graphconv/, and batch.py form the graph-based alignment model and its batching/graph-convolution components.
- prematch/ contains the pre-alignment step, including ICP-based spatial initialization and related utilities.
- preprocess.py, loaddata.py, and utils.py handle data preparation, loading, and shared model-side helpers.
- train.py is the training/inference entry point for model execution.
4. Data flow through the core library
- Input is single-cell spatial omics data from one or more slices/datasets.
- Data is loaded and preprocessed, optionally pre-matched to establish an initial correspondence, then passed into the graph model for alignment.
- The aligned embedding/output is then consumed by metrics, visualization, or downstream biological analysis notebooks.
5. Evaluation subsystem: evaluation/
- This area is a reproducible benchmarking pipeline for comparing SLAT against other methods under controlled conditions.
- It uses Snakemake workflows (workflow/*.smk) to orchestrate dataset preparation, method execution, metric computation, and summarization.
- It includes method-specific notebook runners for Harmony, PASTE, SLAT, STAGATE, Seurat, and LGCN, plus scripts to aggregate results.
6. Benchmark subsystem: benchmark/
- benchmark/ is a broader benchmarking suite, with Snakemake workflows, method notebooks, and analysis notebooks.
- It supports dataset splitting, 2D/3D alignment experiments, scalability analysis, perturbation experiments, and metric aggregation.
- The resource/paste2/ directory includes vendored PASTE2 code used as a benchmarked method dependency rather than as part of the core library.
7. Case study subsystem: case/
- case/ contains notebook-driven reproductions of paper case studies across several experimental scenarios.
- Examples include mouse development, cross-platform spatial alignment, multi-dataset alignment, time-series alignment, and spatial multi-omics.
- These notebooks are analysis clients of the core package and of competing methods; they are not reusable library layers.
8. Documentation subsystem: docs/
- The docs are built as Sphinx-style documentation with tutorials, API pages, installation instructions, and release notes.
- Tutorials are notebook-based and demonstrate core workflows such as basic usage, cross-technology alignment, multi-dataset alignment, pre-matching, and time-series use cases.
- This is the primary human-facing explanation layer for the package API and expected usage patterns.
9. Environment and reproducibility layer: env/ and renv/
- The repo includes explicit environment definitions for multiple comparison methods and R-based components.
- Separate Dockerfiles exist for PASTE, PASTE2, STAGATE, STAGATE_pyg, and Seurat, reflecting that evaluation depends on heterogeneous toolchains.
- The root renv and the Seurat-specific renv show that some workflows depend on R environments in addition to Python.
10. Data preparation layer: data/
- data/ holds dataset preparation guidance and preprocessing notebooks.
- The repository expects data to be downloaded and preprocessed before running the benchmark/evaluation pipelines, which means data acquisition is an external step, not embedded in the package runtime.
11. Workflow orchestration
- Snakemake is the main orchestration technology for benchmark and evaluation runs.
- Workflows split into data preparation, method execution, metric calculation, and summarization, with notebook-based execution used for method-specific runs and analysis notebooks used for postprocessing.
- There are local and HPC-oriented profiles (local, impetus) and Slurm-related folders, so the pipelines are designed to run both on a workstation and on a cluster.
12. External interfaces and packaging
- The Python package is configured via pyproject.toml and distributed via PyPI.
- A Dockerfile at the repo root supports containerized execution, and GitHub Actions build/release workflows automate CI/CD.
- Read the Docs is used for hosted documentation, and the README points to a published paper and tutorial site as the primary external entry points.
13. Main architectural boundary
- The cleanest diagram boundary is: core alignment library in scSLAT versus experiment orchestration in benchmark, evaluation, and case.
- The core library is reusable and versioned; the surrounding directories are reproducibility scaffolding for papers, benchmarks, and case studies.
14. What an architecture diagram should show
- A central scSLAT box with submodules for preprocessing/loading, pre-matching, graph model/training, metrics, and visualization.
- Incoming data from spatial omics datasets, optionally via preprocessing notebooks.
- Outgoing flows to benchmark/evaluation pipelines and case-study notebooks.
- Supporting layers for docs, Docker/environment definitions, and Snakemake-based execution on local or Slurm-backed environments.
Main entry points: scSLAT scSLAT · model Model stack · workflow Workflows · benchmark Benchmark
Components 20
Core library
Reusable Python package for SLAT alignment and downstream analysis.
- scSLAT · Core alignment library published as the reusable runtime API.
scSLAT - Model stack · Loads data, pre-matches slices, builds the graph model, and runs training/inference.
scSLAT/model - Preprocess · Input preprocessing and feature preparation for spatial omics slices.
scSLAT/model/preprocess.py - Load data · Dataset loading and slice assembly for model execution.
scSLAT/model/loaddata.py - Pre-match · Spatial initialization and ICP-based correspondence seeding before graph alignment.
scSLAT/model/prematch - Graph model · Graph-based SLAT alignment model definition.
scSLAT/model/graphmodel.py - Graph conv · Graph convolution components used by the alignment model.
scSLAT/model/graphconv - Batching · Batch construction and graph batching utilities for training and inference.
scSLAT/model/batch.py - Train / infer · Model training and inference entry point.
scSLAT/model/train.py - Metrics · Core metrics used to assess alignment quality and outcomes.
scSLAT/metrics.py - Visualization · Visualization helpers for aligned embeddings and multi-dataset views.
scSLAT/viz
Experiments
Reproducible benchmark, evaluation, and case-study workflows.
- Benchmark · Large benchmarking pipeline for dataset splits, alignment experiments, scaling, perturbations, and metric aggregation.
benchmark - Evaluation · Controlled comparison pipeline for SLAT and competing methods with reproducible metrics and summaries.
evaluation - Case studies · Paper-style notebook reproductions for biological case studies and comparative analyses.
case - Workflows · Snakemake rules, notebooks, and scripts that coordinate preparation, method runs, metrics, and summarization.
benchmark/workflow
Support
Documentation, data prep, and environment definitions.
- Docs · Human-facing documentation, tutorials, API pages, installation guidance, and release notes.
docs - Data prep · Dataset preparation guidance and preprocessing notebooks before benchmark or evaluation runs.
data - Environments · Container and R/Python environment definitions for heterogeneous comparison methods.
env - CI / release · GitHub Actions and packaging/release automation around the Python library and docs.
.github/workflows
Other components
- slat · Repository boundary for the SLAT package and its reproducible experiment stacks.
Connections 32
- slat → scSLAT: contains · Repository contains the reusable Python package.
- slat → Benchmark: hosts · Repository hosts the benchmarking suite.
- slat → Evaluation: hosts · Repository hosts the evaluation suite.
- slat → Case studies: hosts · Repository hosts the case-study notebooks.
- slat → Docs: documents · Repository includes Sphinx-style documentation.
- slat → Data prep: prepares · Repository includes preprocessing guidance and notebooks.
- slat → Environments: defines · Repository includes environment definitions for methods and runtimes.
- slat → CI / release: automates · Repository includes CI and release workflows.
- scSLAT → Model stack: exposes · Core package exposes the alignment runtime stack.
- scSLAT → Metrics: exposes · Core package exposes metrics utilities.
- scSLAT → Visualization: exposes · Core package exposes visualization helpers.
- Model stack → Preprocess: uses · Model stack preprocesses inputs before alignment.
- Model stack → Load data: uses · Model stack loads slices and datasets.
- Model stack → Pre-match: uses · Model stack can seed alignment with pre-matching.
- Model stack → Graph model: builds · Model stack centers on the graph alignment model.
- Graph model → Graph conv: depends on · Graph model uses graph convolution components.
- Graph model → Batching: depends on · Graph model relies on batching utilities.
- Model stack → Train / infer: runs via · Training and inference entry point executes the stack.
- Benchmark → Workflows: orchestrates · Benchmarking is organized as Snakemake workflows.
- Evaluation → Workflows: orchestrates · Evaluation is organized as Snakemake workflows.
- Workflows → Metrics: computes · Workflow stages derive metrics from embeddings and results.
- Workflows → Benchmark: executes · Workflows run benchmark methods and analysis steps.
- Workflows → Evaluation: executes · Workflows run comparison methods and summarization.
- Case studies → scSLAT: consumes · Case-study notebooks use the core library as an analysis client.
- Case studies → Environments: references · Case studies may depend on external method environments.
- Docs → scSLAT: explains · Documentation describes the package API and workflows.
- Data prep → Benchmark: feeds · Prepared datasets feed benchmark runs.
- Data prep → Evaluation: feeds · Prepared datasets feed evaluation runs.
- Environments → Benchmark: supports · Environment definitions support benchmarked external methods.
- Environments → Evaluation: supports · Environment definitions support comparison methods.
- CI / release → scSLAT: packages · CI builds and releases the Python package.
- CI / release → Docs: publishes · CI supports documentation build and hosting.