# toruokadaoi/spatial-graph-bench architecture

> Architecture diagram of the GitHub repository toruokadaoi/spatial-graph-bench, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toruokadaoi/spatial-graph-bench
- Repository: https://github.com/toruokadaoi/spatial-graph-bench

## Overview

spatial-graph-bench is a spatial-transcriptomics research benchmark. A researcher supplies a dataset and experiment configurations; the system creates leakage-safe donor/section/replicate splits, fits frozen features on training cells, builds physical or expression-space graphs, trains matched MLP, Random Forest, and GNN models, computes partition and boundary metrics, and compares GNN Macro-F1 with the matched MLP baseline. Graph rewiring and coordinate shuffling provide negative controls, while manifests and audits verify provenance. The graph reflects sampled runtime code plus README-documented capabilities; several orchestration scripts were not inspected.

Main entry points: [`src/spatial_graph_bench/models/trainer.py`](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/trainer.py) (Training Orchestrator), [`src/spatial_graph_bench/preprocessing/schema.py`](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/preprocessing/schema.py) (Feature Bundle), [`src/spatial_graph_bench/graph/spatial_knn.py`](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/spatial_knn.py) (Spatial k-NN), [`src/spatial_graph_bench/preprocessing/pipeline.py`](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/preprocessing/pipeline.py) (Feature Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol & Features"]
  node_split_config["Split Config<br/>[split.py]"]
  node_splitter["Split Generator<br/>[generator.py]"]
  node_preprocess_config["Preprocessing Config<br/>[preprocessing.py]"]
  node_preprocessor["Feature Pipeline<br/>[pipeline.py]"]
  node_feature_bundle["Feature Bundle<br/>[schema.py]"]
end

subgraph group_graphs["Graph Construction"]
  node_graph_config["Graph Config<br/>[graph.py]"]
  node_graph_registry["Graph Registry<br/>[registry.py]"]
  node_spatial_knn["Spatial k-NN<br/>[spatial_knn.py]"]
  node_bipartite["Reference Bipartite<br/>[bipartite.py]"]
  node_negative_controls["Topology Controls<br/>[rewired_control.py]"]
end

subgraph group_models["Model Training"]
  node_mlp["MLP Baseline<br/>[mlp.py]"]
  node_random_forest["Random Forest<br/>[random_forest.py]"]
  node_gnn["Spatial GNNs<br/>[gnn.py]"]
  node_trainer["Training Orchestrator<br/>[trainer.py]"]
end

subgraph group_results["Evaluation &amp; Provenance"]
  node_metrics["Partition Metrics<br/>[metrics.py]"]
  node_graph_lift["Matched Graph Lift<br/>[graph_lift.py]"]
  node_audit_delivery["Artifact Audit<br/>[delivery.py]"]
  node_evaluation_schema["Evaluation Schema<br/>[schema.py]"]
end

node_researcher(("Researcher"))
node_dataset[("Transcriptomics Dataset")]

node_researcher -->|"provides data"| node_dataset
node_researcher -->|"sets split"| node_split_config
node_researcher -->|"sets features"| node_preprocess_config
node_researcher -->|"selects graph"| node_graph_config
node_dataset -->|"supplies observations"| node_splitter
node_split_config -->|"configures split"| node_splitter
node_splitter -->|"provides partitions"| node_preprocessor
node_dataset -->|"supplies counts"| node_preprocessor
node_preprocess_config -->|"configures pipeline"| node_preprocessor
node_preprocessor -->|"creates features"| node_feature_bundle
node_feature_bundle -->|"provides coordinates"| node_spatial_knn
node_feature_bundle -->|"provides PCA features"| node_bipartite
node_graph_config -->|"selects builder"| node_graph_registry
node_graph_registry -->|"dispatches builder"| node_spatial_knn
node_graph_registry -->|"dispatches builder"| node_bipartite
node_spatial_knn -.->|"provides control graph"| node_negative_controls
node_feature_bundle -->|"provides features"| node_trainer
node_spatial_knn -->|"provides topology"| node_trainer
node_bipartite -->|"provides topology"| node_trainer
node_negative_controls -.->|"provides controls"| node_trainer
node_trainer -->|"trains baseline"| node_mlp
node_trainer -->|"trains baseline"| node_random_forest
node_trainer -->|"trains models"| node_gnn
node_trainer -->|"computes scores"| node_metrics
node_metrics -->|"records summaries"| node_evaluation_schema
node_metrics -->|"feeds scores"| node_graph_lift
node_graph_lift -->|"reports lift"| node_researcher
node_trainer -->|"writes run artifacts"| node_audit_delivery
node_audit_delivery -->|"verifies results"| node_researcher

click node_split_config "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/config/split.py"
click node_splitter "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/splitting/generator.py"
click node_preprocess_config "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/config/preprocessing.py"
click node_preprocessor "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/preprocessing/pipeline.py"
click node_feature_bundle "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/preprocessing/schema.py"
click node_graph_config "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/config/graph.py"
click node_graph_registry "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/registry.py"
click node_spatial_knn "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/spatial_knn.py"
click node_bipartite "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/bipartite.py"
click node_negative_controls "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/rewired_control.py"
click node_mlp "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/mlp.py"
click node_random_forest "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/random_forest.py"
click node_gnn "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/gnn.py"
click node_trainer "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/trainer.py"
click node_metrics "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/evaluation/metrics.py"
click node_graph_lift "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/tracking/graph_lift.py"
click node_audit_delivery "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/analysis/delivery.py"
click node_evaluation_schema "https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/evaluation/schema.py"

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_split_config,node_splitter,node_preprocess_config,node_preprocessor,node_feature_bundle toneBlue
class node_graph_config,node_graph_registry,node_spatial_knn,node_bipartite,node_negative_controls,node_dataset toneAmber
class node_mlp,node_random_forest,node_gnn,node_trainer toneMint
class node_metrics,node_graph_lift,node_audit_delivery,node_evaluation_schema toneRose
class node_researcher toneIndigo
```

## Components

### Protocol & Features

- [Split Config](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/config/split.py): `src/spatial_graph_bench/config/split.py`
- [Split Generator](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/splitting/generator.py): `src/spatial_graph_bench/splitting/generator.py`
- [Preprocessing Config](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/config/preprocessing.py): `src/spatial_graph_bench/config/preprocessing.py`
- [Feature Pipeline](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/preprocessing/pipeline.py): `src/spatial_graph_bench/preprocessing/pipeline.py`
- [Feature Bundle](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/preprocessing/schema.py): `src/spatial_graph_bench/preprocessing/schema.py`

### Graph Construction

- [Graph Config](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/config/graph.py): `src/spatial_graph_bench/config/graph.py`
- [Graph Registry](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/registry.py): `src/spatial_graph_bench/graph/registry.py`
- [Spatial k-NN](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/spatial_knn.py): `src/spatial_graph_bench/graph/spatial_knn.py`
- [Reference Bipartite](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/bipartite.py): `src/spatial_graph_bench/graph/bipartite.py`
- [Topology Controls](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/graph/rewired_control.py): `src/spatial_graph_bench/graph/rewired_control.py`

### Model Training

- [MLP Baseline](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/mlp.py): `src/spatial_graph_bench/models/mlp.py`
- [Random Forest](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/random_forest.py): `src/spatial_graph_bench/models/random_forest.py`
- [Spatial GNNs](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/gnn.py): `src/spatial_graph_bench/models/gnn.py`
- [Training Orchestrator](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/models/trainer.py): `src/spatial_graph_bench/models/trainer.py`

### Evaluation & Provenance

- [Partition Metrics](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/evaluation/metrics.py): `src/spatial_graph_bench/evaluation/metrics.py`
- [Matched Graph Lift](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/tracking/graph_lift.py): `src/spatial_graph_bench/tracking/graph_lift.py`
- [Artifact Audit](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/analysis/delivery.py): `src/spatial_graph_bench/analysis/delivery.py`
- [Evaluation Schema](https://github.com/toruokadaoi/spatial-graph-bench/blob/main/src/spatial_graph_bench/evaluation/schema.py): `src/spatial_graph_bench/evaluation/schema.py`

### Other components

- **Researcher**
- **Transcriptomics Dataset**

## Connections

- Researcher → Transcriptomics Dataset: provides data
- Researcher → Split Config: sets split
- Researcher → Preprocessing Config: sets features
- Researcher → Graph Config: selects graph
- Transcriptomics Dataset → Split Generator: supplies observations
- Split Config → Split Generator: configures split
- Split Generator → Feature Pipeline: provides partitions
- Transcriptomics Dataset → Feature Pipeline: supplies counts
- Preprocessing Config → Feature Pipeline: configures pipeline
- Feature Pipeline → Feature Bundle: creates features
- Feature Bundle → Spatial k-NN: provides coordinates
- Feature Bundle → Reference Bipartite: provides PCA features
- Graph Config → Graph Registry: selects builder
- Graph Registry → Spatial k-NN: dispatches builder
- Graph Registry → Reference Bipartite: dispatches builder
- Spatial k-NN → Topology Controls: provides control graph
- Feature Bundle → Training Orchestrator: provides features
- Spatial k-NN → Training Orchestrator: provides topology
- Reference Bipartite → Training Orchestrator: provides topology
- Topology Controls → Training Orchestrator: provides controls
- Training Orchestrator → MLP Baseline: trains baseline
- Training Orchestrator → Random Forest: trains baseline
- Training Orchestrator → Spatial GNNs: trains models
- Training Orchestrator → Partition Metrics: computes scores
- Partition Metrics → Evaluation Schema: records summaries
- Partition Metrics → Matched Graph Lift: feeds scores
- Matched Graph Lift → Researcher: reports lift
- Training Orchestrator → Artifact Audit: writes run artifacts
- Artifact Audit → Researcher: verifies results