# gao-lab/slat architecture

> Architecture diagram of the GitHub repository gao-lab/slat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gao-lab/slat
- Repository: https://github.com/gao-lab/slat

## Overview

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`](https://github.com/gao-lab/slat/tree/main/scSLAT) (scSLAT), [`scSLAT/model`](https://github.com/gao-lab/slat/tree/main/scSLAT/model) (Model stack), [`benchmark/workflow`](https://github.com/gao-lab/slat/tree/main/benchmark/workflow) (Workflows), [`benchmark`](https://github.com/gao-lab/slat/tree/main/benchmark) (Benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_scslat["scSLAT<br/>python package"]
  node_model["Model stack<br/>alignment runtime"]
  node_preprocess["Preprocess<br/>data prep<br/>[preprocess.py]"]
  node_loaddata["Load data<br/>dataset loader<br/>[loaddata.py]"]
  node_prematch["Pre-match<br/>init alignment"]
  node_graphmodel["Graph model<br/>alignment model<br/>[graphmodel.py]"]
  node_graphconv["Graph conv<br/>message passing"]
  node_batching["Batching<br/>[batch.py]"]
  node_train["Train / infer<br/>execution entry<br/>[train.py]"]
  node_metrics["Metrics<br/>evaluation utils<br/>[metrics.py]"]
  node_viz["Visualization<br/>plot helpers"]
end

subgraph group_experiments["Experiments"]
  node_benchmark["Benchmark<br/>snakemake suite"]
  node_evaluation["Evaluation<br/>snakemake suite"]
  node_case["Case studies<br/>notebook analyses"]
  node_workflows["Workflows<br/>snakemake orchestration"]
end

subgraph group_support["Support"]
  node_docs["Docs"]
  node_data["Data prep<br/>dataset prep"]
  node_env["Environments<br/>tooling envs"]
  node_ci["CI / release<br/>automation<br/>[workflows]"]
end

node_repo{{"slat<br/>research repo"}}

node_repo -->|"contains"| node_scslat
node_repo -->|"hosts"| node_benchmark
node_repo -->|"hosts"| node_evaluation
node_repo -->|"hosts"| node_case
node_repo -->|"documents"| node_docs
node_repo -->|"prepares"| node_data
node_repo -->|"defines"| node_env
node_repo -->|"automates"| node_ci
node_scslat -->|"exposes"| node_model
node_scslat -->|"exposes"| node_metrics
node_scslat -->|"exposes"| node_viz
node_model -->|"uses"| node_preprocess
node_model -->|"uses"| node_loaddata
node_model -->|"uses"| node_prematch
node_model -->|"builds"| node_graphmodel
node_graphmodel -->|"depends on"| node_graphconv
node_graphmodel -->|"depends on"| node_batching
node_model -->|"runs via"| node_train
node_benchmark -->|"orchestrates"| node_workflows
node_evaluation -->|"orchestrates"| node_workflows
node_workflows -->|"computes"| node_metrics
node_workflows -->|"executes"| node_benchmark
node_workflows -->|"executes"| node_evaluation
node_case -->|"consumes"| node_scslat
node_case -->|"references"| node_env
node_docs -->|"explains"| node_scslat
node_data -->|"feeds"| node_benchmark
node_data -->|"feeds"| node_evaluation
node_env -->|"supports"| node_benchmark
node_env -->|"supports"| node_evaluation
node_ci -->|"packages"| node_scslat
node_ci -->|"publishes"| node_docs

click node_scslat "https://github.com/gao-lab/slat/tree/main/scSLAT"
click node_model "https://github.com/gao-lab/slat/tree/main/scSLAT/model"
click node_preprocess "https://github.com/gao-lab/slat/blob/main/scSLAT/model/preprocess.py"
click node_loaddata "https://github.com/gao-lab/slat/blob/main/scSLAT/model/loaddata.py"
click node_prematch "https://github.com/gao-lab/slat/tree/main/scSLAT/model/prematch"
click node_graphmodel "https://github.com/gao-lab/slat/blob/main/scSLAT/model/graphmodel.py"
click node_graphconv "https://github.com/gao-lab/slat/tree/main/scSLAT/model/graphconv"
click node_batching "https://github.com/gao-lab/slat/blob/main/scSLAT/model/batch.py"
click node_train "https://github.com/gao-lab/slat/blob/main/scSLAT/model/train.py"
click node_metrics "https://github.com/gao-lab/slat/blob/main/scSLAT/metrics.py"
click node_viz "https://github.com/gao-lab/slat/tree/main/scSLAT/viz"
click node_benchmark "https://github.com/gao-lab/slat/tree/main/benchmark"
click node_evaluation "https://github.com/gao-lab/slat/tree/main/evaluation"
click node_case "https://github.com/gao-lab/slat/tree/main/case"
click node_workflows "https://github.com/gao-lab/slat/tree/main/benchmark/workflow"
click node_docs "https://github.com/gao-lab/slat/tree/main/docs"
click node_data "https://github.com/gao-lab/slat/tree/main/data"
click node_env "https://github.com/gao-lab/slat/tree/main/env"
click node_ci "https://github.com/gao-lab/slat/blob/main/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scslat,node_model,node_preprocess,node_loaddata,node_prematch,node_graphmodel,node_graphconv,node_batching,node_train,node_metrics,node_viz toneBlue
class node_benchmark,node_evaluation,node_case,node_workflows toneAmber
class node_docs,node_data,node_env,node_ci toneMint
class node_repo toneNeutral
```

## Components

### Core library

Reusable Python package for SLAT alignment and downstream analysis.

- [scSLAT](https://github.com/gao-lab/slat/tree/main/scSLAT): python package · Core alignment library published as the reusable runtime API. · `scSLAT`
- [Model stack](https://github.com/gao-lab/slat/tree/main/scSLAT/model): alignment runtime · Loads data, pre-matches slices, builds the graph model, and runs training/inference. · `scSLAT/model`
- [Preprocess](https://github.com/gao-lab/slat/blob/main/scSLAT/model/preprocess.py): data prep · Input preprocessing and feature preparation for spatial omics slices. · `scSLAT/model/preprocess.py`
- [Load data](https://github.com/gao-lab/slat/blob/main/scSLAT/model/loaddata.py): dataset loader · Dataset loading and slice assembly for model execution. · `scSLAT/model/loaddata.py`
- [Pre-match](https://github.com/gao-lab/slat/tree/main/scSLAT/model/prematch): init alignment · Spatial initialization and ICP-based correspondence seeding before graph alignment. · `scSLAT/model/prematch`
- [Graph model](https://github.com/gao-lab/slat/blob/main/scSLAT/model/graphmodel.py): alignment model · Graph-based SLAT alignment model definition. · `scSLAT/model/graphmodel.py`
- [Graph conv](https://github.com/gao-lab/slat/tree/main/scSLAT/model/graphconv): message passing · Graph convolution components used by the alignment model. · `scSLAT/model/graphconv`
- [Batching](https://github.com/gao-lab/slat/blob/main/scSLAT/model/batch.py): tensor batching · Batch construction and graph batching utilities for training and inference. · `scSLAT/model/batch.py`
- [Train / infer](https://github.com/gao-lab/slat/blob/main/scSLAT/model/train.py): execution entry · Model training and inference entry point. · `scSLAT/model/train.py`
- [Metrics](https://github.com/gao-lab/slat/blob/main/scSLAT/metrics.py): evaluation utils · Core metrics used to assess alignment quality and outcomes. · `scSLAT/metrics.py`
- [Visualization](https://github.com/gao-lab/slat/tree/main/scSLAT/viz): plot helpers · Visualization helpers for aligned embeddings and multi-dataset views. · `scSLAT/viz`

### Experiments

Reproducible benchmark, evaluation, and case-study workflows.

- [Benchmark](https://github.com/gao-lab/slat/tree/main/benchmark): snakemake suite · Large benchmarking pipeline for dataset splits, alignment experiments, scaling, perturbations, and metric aggregation. · `benchmark`
- [Evaluation](https://github.com/gao-lab/slat/tree/main/evaluation): snakemake suite · Controlled comparison pipeline for SLAT and competing methods with reproducible metrics and summaries. · `evaluation`
- [Case studies](https://github.com/gao-lab/slat/tree/main/case): notebook analyses · Paper-style notebook reproductions for biological case studies and comparative analyses. · `case`
- [Workflows](https://github.com/gao-lab/slat/tree/main/benchmark/workflow): snakemake orchestration · Snakemake rules, notebooks, and scripts that coordinate preparation, method runs, metrics, and summarization. · `benchmark/workflow`

### Support

Documentation, data prep, and environment definitions.

- [Docs](https://github.com/gao-lab/slat/tree/main/docs): sphinx docs · Human-facing documentation, tutorials, API pages, installation guidance, and release notes. · `docs`
- [Data prep](https://github.com/gao-lab/slat/tree/main/data): dataset prep · Dataset preparation guidance and preprocessing notebooks before benchmark or evaluation runs. · `data`
- [Environments](https://github.com/gao-lab/slat/tree/main/env): tooling envs · Container and R/Python environment definitions for heterogeneous comparison methods. · `env`
- [CI / release](https://github.com/gao-lab/slat/blob/main/.github/workflows): automation · GitHub Actions and packaging/release automation around the Python library and docs. · `.github/workflows`

### Other components

- **slat**: research repo · Repository boundary for the SLAT package and its reproducible experiment stacks.

## Connections

- 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.