# khanlab/spimquant architecture

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

- Interactive diagram: https://gitdiagram.com/khanlab/spimquant
- Repository: https://github.com/khanlab/spimquant

## Overview

SPIMquant is a Snakebids application for automated lightsheet-brain registration and atlas-based pathology quantification. A participant supplies a BIDS dataset and selects a run; the app hands execution to its Snakemake workflow, which produces subject-level measurements and QC. Group runs combine measurements with participant metadata for model-based contrasts and visualization. The tree lists workflow scripts but not the workflow definition, so internal stage wiring is necessarily summarized; the feature branches below reflect the README and script names, not inspected workflow rules.

Main entry points: [`spimquant/workflow`](https://github.com/khanlab/spimquant/tree/main/spimquant/workflow) (Snakemake workflow), [`spimquant/run.py`](https://github.com/khanlab/spimquant/blob/main/spimquant/run.py) (BIDS app), [`spimquant/workflow/scripts/perform_group_stats.py`](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/perform_group_stats.py) (Group statistics), [`spimquant/workflow/scripts/create_stats_heatmap.py`](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/create_stats_heatmap.py) (Stats visualizations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and orchestration"]
  node_app["BIDS app<br/>[run.py]"]
  node_workflow["Snakemake workflow"]
end

subgraph group_imaging["Image processing"]
  node_segmentation["Segmentation"]
  node_registration["Template registration"]
  node_registration_qc["Registration QC<br/>[reg_qc_report.py]"]
  node_image_qc["Image QC"]
end

subgraph group_quantification["Quantification"]
  node_regionprops["Object measurements"]
  node_atlas_mapping["Atlas mapping"]
  node_colocalization["Colocalization"]
  node_vessel_analysis["Vessel analysis"]
  node_imaris["Imaris crops"]
end

subgraph group_analysis["Analysis and outputs"]
  node_subject_stats["Subject statistics"]
  node_group_stats["Group statistics"]
  node_visualization["Stats visualizations"]
end

node_participant(("Researcher"))
node_bids["BIDS dataset"]
node_cloud_storage[("Cloud storage")]
node_cloud_compute["Coiled compute"]
node_results["Analysis outputs"]

node_participant -->|"starts run"| node_app
node_bids -->|"provides dataset"| node_app
node_app -->|"hands off"| node_workflow
node_workflow -->|"dispatches"| node_segmentation
node_workflow -->|"dispatches"| node_registration
node_workflow -->|"dispatches"| node_registration_qc
node_workflow -->|"dispatches"| node_image_qc
node_workflow -->|"dispatches"| node_regionprops
node_workflow -->|"dispatches"| node_atlas_mapping
node_workflow -->|"dispatches"| node_colocalization
node_workflow -->|"dispatches"| node_vessel_analysis
node_workflow -->|"dispatches"| node_imaris
node_workflow -->|"dispatches"| node_subject_stats
node_workflow -->|"dispatches"| node_group_stats
node_workflow -->|"dispatches"| node_visualization
node_group_stats -->|"results feed"| node_visualization
node_workflow -->|"writes"| node_results
node_cloud_storage -.->|"supplies data"| node_workflow
node_workflow -.->|"offloads processing"| node_cloud_compute

click node_app "https://github.com/khanlab/spimquant/blob/main/spimquant/run.py"
click node_workflow "https://github.com/khanlab/spimquant/tree/main/spimquant/workflow"
click node_segmentation "https://github.com/khanlab/spimquant/tree/main/spimquant/workflow/scripts"
click node_registration "https://github.com/khanlab/spimquant/tree/main/spimquant/workflow"
click node_registration_qc "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/reg_qc_report.py"
click node_image_qc "https://github.com/khanlab/spimquant/tree/main/spimquant/workflow/scripts"
click node_regionprops "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/compute_filtered_regionprops.py"
click node_atlas_mapping "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/map_atlas_to_regionprops.py"
click node_colocalization "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/compute_colocalization.py"
click node_vessel_analysis "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/skeleton_graph_from_sdt.py"
click node_imaris "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/create_imaris_crops.py"
click node_subject_stats "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/merge_into_segstats_tsv.py"
click node_group_stats "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/perform_group_stats.py"
click node_visualization "https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/create_stats_heatmap.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_app,node_workflow toneBlue
class node_segmentation,node_registration,node_registration_qc,node_image_qc,node_cloud_storage toneAmber
class node_regionprops,node_atlas_mapping,node_colocalization,node_vessel_analysis,node_imaris toneMint
class node_subject_stats,node_group_stats,node_visualization toneRose
class node_participant,node_bids,node_cloud_compute,node_results toneIndigo
```

## Components

### App and orchestration

- [BIDS app](https://github.com/khanlab/spimquant/blob/main/spimquant/run.py): `spimquant/run.py`
- [Snakemake workflow](https://github.com/khanlab/spimquant/tree/main/spimquant/workflow): `spimquant/workflow`

### Image processing

- [Segmentation](https://github.com/khanlab/spimquant/tree/main/spimquant/workflow/scripts): `spimquant/workflow/scripts`
- [Template registration](https://github.com/khanlab/spimquant/tree/main/spimquant/workflow): `spimquant/workflow`
- [Registration QC](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/reg_qc_report.py): `spimquant/workflow/scripts/reg_qc_report.py`
- [Image QC](https://github.com/khanlab/spimquant/tree/main/spimquant/workflow/scripts): `spimquant/workflow/scripts`

### Quantification

- [Object measurements](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/compute_filtered_regionprops.py): `spimquant/workflow/scripts/compute_filtered_regionprops.py`
- [Atlas mapping](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/map_atlas_to_regionprops.py): `spimquant/workflow/scripts/map_atlas_to_regionprops.py`
- [Colocalization](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/compute_colocalization.py): `spimquant/workflow/scripts/compute_colocalization.py`
- [Vessel analysis](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/skeleton_graph_from_sdt.py): `spimquant/workflow/scripts/skeleton_graph_from_sdt.py`
- [Imaris crops](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/create_imaris_crops.py): `spimquant/workflow/scripts/create_imaris_crops.py`

### Analysis and outputs

- [Subject statistics](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/merge_into_segstats_tsv.py): `spimquant/workflow/scripts/merge_into_segstats_tsv.py`
- [Group statistics](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/perform_group_stats.py): `spimquant/workflow/scripts/perform_group_stats.py`
- [Stats visualizations](https://github.com/khanlab/spimquant/blob/main/spimquant/workflow/scripts/create_stats_heatmap.py): `spimquant/workflow/scripts/create_stats_heatmap.py`

### Other components

- **Researcher**
- **BIDS dataset**
- **Cloud storage**
- **Coiled compute**
- **Analysis outputs**

## Connections

- Researcher → BIDS app: starts run
- BIDS dataset → BIDS app: provides dataset
- BIDS app → Snakemake workflow: hands off
- Snakemake workflow → Segmentation: dispatches
- Snakemake workflow → Template registration: dispatches
- Snakemake workflow → Registration QC: dispatches
- Snakemake workflow → Image QC: dispatches
- Snakemake workflow → Object measurements: dispatches
- Snakemake workflow → Atlas mapping: dispatches
- Snakemake workflow → Colocalization: dispatches
- Snakemake workflow → Vessel analysis: dispatches
- Snakemake workflow → Imaris crops: dispatches
- Snakemake workflow → Subject statistics: dispatches
- Snakemake workflow → Group statistics: dispatches
- Snakemake workflow → Stats visualizations: dispatches
- Group statistics → Stats visualizations: results feed
- Snakemake workflow → Analysis outputs: writes
- Cloud storage → Snakemake workflow: supplies data
- Snakemake workflow → Coiled compute: offloads processing