# snap-stanford/gears architecture

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

- Interactive diagram: https://gitdiagram.com/snap-stanford/gears
- Repository: https://github.com/snap-stanford/gears

## Overview

GEARS turns perturbational single-cell data into predictions of transcriptional responses, including combinatorial perturbations. The main workflow is to load or preprocess data, define perturbation splits and batches, initialize and train the model, then predict and evaluate responses; the API also exposes genetic-interaction analysis. The graph preserves documented dataset, uncertainty, and plotting capabilities. Some subsystem links rely on the README or SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`gears/pertdata.py`](https://github.com/snap-stanford/gears/blob/master/gears/pertdata.py) (PertData API), [`gears/gears.py`](https://github.com/snap-stanford/gears/blob/master/gears/gears.py) (GEARS API), [`gears/model.py`](https://github.com/snap-stanford/gears/blob/master/gears/model.py) (GEARS neural model), [`gears/data_utils.py`](https://github.com/snap-stanford/gears/blob/master/gears/data_utils.py) (Data preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Perturbation data"]
  node_pertdata["PertData API<br/>[pertdata.py]"]
  node_preprocess["Data preprocessing<br/>[data_utils.py]"]
  node_cellgraphs["Cell graph datasets<br/>[pertdata.py]"]
  node_splits["Perturbation splits<br/>[data_utils.py]"]
end

subgraph group_modeling["Modeling"]
  node_gears_api["GEARS API<br/>[gears.py]"]
  node_trainer["Training and evaluation<br/>[gears.py]"]
  node_model["GEARS neural model<br/>[model.py]"]
  node_uncertainty["Uncertainty modeling<br/>[model.py]"]
end

subgraph group_analysis["Prediction and analysis"]
  node_prediction["Perturbation prediction<br/>[gears.py]"]
  node_inference["Inference metrics<br/>[inference.py]"]
  node_gi["Genetic interactions<br/>[inference.py]"]
  node_visualization["Result visualization<br/>[gears.py]"]
end

subgraph group_support["Data and graph utilities"]
  node_graph_utils["Gene graph utilities<br/>[utils.py]"]
  node_data_utils["Data download utilities<br/>[utils.py]"]
end

node_researcher(("Researcher"))
node_dataverse["Harvard Dataverse"]

node_researcher -->|"loads data"| node_pertdata
node_pertdata -->|"preprocesses data"| node_preprocess
node_pertdata -->|"prepares splits"| node_splits
node_pertdata -->|"builds batches"| node_cellgraphs
node_pertdata -->|"uses utilities"| node_data_utils
node_pertdata -->|"downloads resources"| node_dataverse
node_researcher -->|"initializes model"| node_gears_api
node_gears_api -->|"trains model"| node_trainer
node_trainer -->|"optimizes"| node_model
node_trainer -->|"evaluates with"| node_inference
node_model -->|"supports"| node_uncertainty
node_researcher -->|"requests predictions"| node_prediction
node_gears_api -->|"dispatches prediction"| node_prediction
node_prediction -->|"runs forward pass"| node_model
node_gears_api -->|"uses metrics"| node_inference
node_gears_api -->|"computes interactions"| node_gi
node_gears_api -->|"plots results"| node_visualization
node_preprocess -->|"uses graph helpers"| node_graph_utils
node_graph_utils -->|"downloads graph data"| node_dataverse

click node_pertdata "https://github.com/snap-stanford/gears/blob/master/gears/pertdata.py"
click node_preprocess "https://github.com/snap-stanford/gears/blob/master/gears/data_utils.py"
click node_cellgraphs "https://github.com/snap-stanford/gears/blob/master/gears/pertdata.py"
click node_splits "https://github.com/snap-stanford/gears/blob/master/gears/data_utils.py"
click node_gears_api "https://github.com/snap-stanford/gears/blob/master/gears/gears.py"
click node_trainer "https://github.com/snap-stanford/gears/blob/master/gears/gears.py"
click node_model "https://github.com/snap-stanford/gears/blob/master/gears/model.py"
click node_uncertainty "https://github.com/snap-stanford/gears/blob/master/gears/model.py"
click node_prediction "https://github.com/snap-stanford/gears/blob/master/gears/gears.py"
click node_inference "https://github.com/snap-stanford/gears/blob/master/gears/inference.py"
click node_gi "https://github.com/snap-stanford/gears/blob/master/gears/inference.py"
click node_visualization "https://github.com/snap-stanford/gears/blob/master/gears/gears.py"
click node_graph_utils "https://github.com/snap-stanford/gears/blob/master/gears/utils.py"
click node_data_utils "https://github.com/snap-stanford/gears/blob/master/gears/utils.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_pertdata,node_preprocess,node_cellgraphs,node_splits toneBlue
class node_gears_api,node_trainer,node_model,node_uncertainty toneAmber
class node_prediction,node_inference,node_gi,node_visualization toneMint
class node_graph_utils,node_data_utils toneRose
class node_researcher,node_dataverse toneIndigo
```

## Components

### Perturbation data

- [PertData API](https://github.com/snap-stanford/gears/blob/master/gears/pertdata.py): `gears/pertdata.py`
- [Data preprocessing](https://github.com/snap-stanford/gears/blob/master/gears/data_utils.py): `gears/data_utils.py`
- [Cell graph datasets](https://github.com/snap-stanford/gears/blob/master/gears/pertdata.py): `gears/pertdata.py`
- [Perturbation splits](https://github.com/snap-stanford/gears/blob/master/gears/data_utils.py): `gears/data_utils.py`

### Modeling

- [GEARS API](https://github.com/snap-stanford/gears/blob/master/gears/gears.py): `gears/gears.py`
- [Training and evaluation](https://github.com/snap-stanford/gears/blob/master/gears/gears.py): `gears/gears.py`
- [GEARS neural model](https://github.com/snap-stanford/gears/blob/master/gears/model.py): `gears/model.py`
- [Uncertainty modeling](https://github.com/snap-stanford/gears/blob/master/gears/model.py): `gears/model.py`

### Prediction and analysis

- [Perturbation prediction](https://github.com/snap-stanford/gears/blob/master/gears/gears.py): `gears/gears.py`
- [Inference metrics](https://github.com/snap-stanford/gears/blob/master/gears/inference.py): `gears/inference.py`
- [Genetic interactions](https://github.com/snap-stanford/gears/blob/master/gears/inference.py): `gears/inference.py`
- [Result visualization](https://github.com/snap-stanford/gears/blob/master/gears/gears.py): `gears/gears.py`

### Data and graph utilities

- [Gene graph utilities](https://github.com/snap-stanford/gears/blob/master/gears/utils.py): `gears/utils.py`
- [Data download utilities](https://github.com/snap-stanford/gears/blob/master/gears/utils.py): `gears/utils.py`

### Other components

- **Researcher**
- **Harvard Dataverse**

## Connections

- Researcher → PertData API: loads data (evidence: `README.md`)
- PertData API → Data preprocessing: preprocesses data (evidence: `gears/pertdata.py`)
- PertData API → Perturbation splits: prepares splits (evidence: `README.md`)
- PertData API → Cell graph datasets: builds batches (evidence: `gears/pertdata.py`)
- PertData API → Data download utilities: uses utilities (evidence: `gears/pertdata.py`)
- PertData API → Harvard Dataverse: downloads resources (evidence: `gears/pertdata.py`)
- Researcher → GEARS API: initializes model (evidence: `README.md`)
- GEARS API → Training and evaluation: trains model (evidence: `README.md`)
- Training and evaluation → GEARS neural model: optimizes (evidence: `gears/gears.py`)
- Training and evaluation → Inference metrics: evaluates with (evidence: `gears/gears.py`)
- GEARS neural model → Uncertainty modeling: supports (evidence: `gears/model.py`)
- Researcher → Perturbation prediction: requests predictions (evidence: `README.md`)
- GEARS API → Perturbation prediction: dispatches prediction (evidence: `gears/gears.py`)
- Perturbation prediction → GEARS neural model: runs forward pass (evidence: `gears/gears.py`)
- GEARS API → Inference metrics: uses metrics (evidence: `gears/gears.py`)
- GEARS API → Genetic interactions: computes interactions (evidence: `README.md`)
- GEARS API → Result visualization: plots results (evidence: `README.md`)
- Data preprocessing → Gene graph utilities: uses graph helpers (evidence: `gears/data_utils.py`)
- Gene graph utilities → Harvard Dataverse: downloads graph data (evidence: `gears/utils.py`)
