# junhaolixd/biohub_cell_tracking architecture

> Architecture diagram of the GitHub repository junhaolixd/biohub_cell_tracking, 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/junhaolixd/biohub_cell_tracking
- Repository: https://github.com/junhaolixd/biohub_cell_tracking

## Overview

Biohub is a Kaggle cell-tracking solution for 3D time-lapse zebrafish microscopy. Its documented inference workflow takes microscopy data through pretrained 3D detection, learned frame-to-frame association, ILP graph tracking, track repair and division gating, then serializes a competition submission. The repository also contains an experiment controller for managing research runs and reviews. The deployment notebook described in the README is not present in the supplied tree, so several pipeline paths point to the exact enclosing source directories available here; those implementation details are documented rather than sampled directly.

Main entry points: [`experiment_controller/loop.py`](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/loop.py) (Experiment workflow), [`experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py`](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py) (3D detector), [`experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking`](https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking) (Cell detections), [`experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/models/simple_node_transformer.py`](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/models/simple_node_transformer.py) (Transformer association)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_microscopy[("Microscopy data")]
end

subgraph group_inference["Detection"]
  node_detector["3D detector"]
  node_detections["Cell detections"]
end

subgraph group_tracking["Tracking"]
  node_association["Transformer association"]
  node_ilp["ILP tracking"]
  node_repair["Motion and gap repair"]
  node_division["Division gates"]
end

subgraph group_output["Submission"]
  node_graph["Tracking graph<br/>[io.py]"]
  node_submission["submission.csv"]
end

subgraph group_research["Research control"]
  node_experiments["Experiment workflow<br/>[loop.py]"]
  node_review["Review and state<br/>[review.py]"]
  node_record[("Experiment records<br/>[core.py]")]
end

node_user(("Kaggle user"))
node_kaggle(("Kaggle competition"))

node_user -->|"selects data"| node_microscopy
node_microscopy -->|"provides frames"| node_detector
node_detector -->|"predicts cells"| node_detections
node_detections -->|"supplies detections"| node_association
node_association -->|"scores links"| node_ilp
node_ilp -->|"forms tracks"| node_repair
node_repair -->|"repairs tracks"| node_division
node_division -->|"gates divisions"| node_graph
node_graph -->|"serializes graph"| node_submission
node_submission -->|"submits results"| node_kaggle
node_user -->|"manages runs"| node_experiments
node_experiments -->|"updates state"| node_record
node_experiments -->|"requests review"| node_review
node_review -->|"records verdict"| node_record

click node_detector "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py"
click node_detections "https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking"
click node_association "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/models/simple_node_transformer.py"
click node_ilp "https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking"
click node_repair "https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiment_controller"
click node_division "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/division_metrics.py"
click node_graph "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/io.py"
click node_submission "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py"
click node_experiments "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/loop.py"
click node_review "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/review.py"
click node_record "https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/core.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_microscopy,node_user toneBlue
class node_detector,node_detections toneAmber
class node_association,node_ilp,node_repair,node_division toneMint
class node_graph,node_submission toneRose
class node_experiments,node_review,node_record,node_kaggle toneIndigo
```

## Components

### Inputs

- **Microscopy data**

### Detection

- [3D detector](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py`
- [Cell detections](https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking`

### Tracking

- [Transformer association](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/models/simple_node_transformer.py): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/models/simple_node_transformer.py`
- [ILP tracking](https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking`
- [Motion and gap repair](https://github.com/junhaolixd/biohub_cell_tracking/tree/main/experiment_controller): `experiment_controller`
- [Division gates](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/division_metrics.py): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/division_metrics.py`

### Submission

- [Tracking graph](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/io.py): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/src/biohub_tracking/io.py`
- [submission.csv](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py): `experiments/repro_003_public_0933_kaggle_slug/remote_output/tracking_repo/scripts/predict_unet_transformer.py`

### Research control

- [Experiment workflow](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/loop.py): `experiment_controller/loop.py`
- [Review and state](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/review.py): `experiment_controller/review.py`
- [Experiment records](https://github.com/junhaolixd/biohub_cell_tracking/blob/main/experiment_controller/core.py): `experiment_controller/core.py`

### Other components

- **Kaggle user**
- **Kaggle competition**

## Connections

- Kaggle user → Microscopy data: selects data
- Microscopy data → 3D detector: provides frames
- 3D detector → Cell detections: predicts cells
- Cell detections → Transformer association: supplies detections
- Transformer association → ILP tracking: scores links
- ILP tracking → Motion and gap repair: forms tracks
- Motion and gap repair → Division gates: repairs tracks
- Division gates → Tracking graph: gates divisions
- Tracking graph → submission.csv: serializes graph
- submission.csv → Kaggle competition: submits results
- Kaggle user → Experiment workflow: manages runs
- Experiment workflow → Experiment records: updates state
- Experiment workflow → Review and state: requests review
- Review and state → Experiment records: records verdict