# tlobnow/ec_pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/tlobnow/ec_pipeline
- Repository: https://github.com/tlobnow/ec_pipeline

## Overview

ec_pipeline is a microscopy image-analysis toolkit for processing ND2 time-lapse experiments and examining cell behavior and GFP phenotypes. Its principal workflow converts acquisition data into per-channel movies, segments cells, tracks them across frames, then supports inspection, lineage-following, and GFP structure analysis. Separate utilities split ND2 acquisitions, check timing metadata, export cells for manual labeling, and train phenotype classifiers. The README contains no capability overview; component roles come from script names and available docstrings. Some downstream handoffs are not shown in the excerpts, so those relationships are omitted.

Main entry points: [`scripts/common.py`](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/common.py) (Shared helpers), [`scripts/01_load_nd2.py`](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/01_load_nd2.py) (Load channels), [`scripts/04_inspect.py`](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/04_inspect.py) (Inspect tracks), [`scripts/split_nd2.py`](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/split_nd2.py) (Split fields of view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Acquisition"]
  node_config["Experiment settings<br/>[btrack_config.json]"]
  node_split["Split fields of view<br/>[split_nd2.py]"]
  node_load["Load channels<br/>[01_load_nd2.py]"]
  node_timing["Inspect timing"]
end

subgraph group_analysis["Cell Analysis"]
  node_segment["Segment cells<br/>[02_segment.py]"]
  node_track["Track lineages<br/>[03_track.py]"]
  node_inspect["Inspect tracks<br/>[04_inspect.py]"]
  node_single["Follow cell lineage<br/>[05_single_cell.py]"]
end

subgraph group_phenotype["Phenotype Tools"]
  node_gfp["Detect GFP structures"]
  node_tune["Tune GFP calls<br/>[tune_gfp.py]"]
  node_export["Export cell images"]
  node_classify["Classify phenotypes<br/>[classify_cells.py]"]
  node_convpaint["Train ConvPaint<br/>[train_convpaint.py]"]
end

subgraph group_shared["Shared Runtime"]
  node_common["Shared helpers<br/>[common.py]"]
end

node_user(("Microscopy analyst"))
node_nd2["ND2 experiment"]

node_user -->|"configures"| node_config
node_user -->|"selects input"| node_nd2
node_split -->|"splits fields"| node_nd2
node_load -->|"reads images"| node_nd2
node_timing -->|"reads metadata"| node_nd2
node_segment -->|"reads channel TIFF"| node_load
node_inspect -->|"reads channel TIFFs"| node_load
node_inspect -->|"reads tracked masks"| node_track
node_user -.->|"runs"| node_split
node_user -.->|"runs"| node_load
node_user -.->|"runs"| node_segment
node_user -.->|"runs"| node_track
node_user -.->|"reviews"| node_inspect
node_user -.->|"selects cell"| node_single
node_user -.->|"analyzes"| node_gfp
node_user -.->|"tunes calls"| node_tune
node_user -.->|"exports cells"| node_export
node_user -.->|"trains or applies"| node_classify
node_user -.->|"trains"| node_convpaint
node_load -->|"uses helpers"| node_common
node_segment -->|"uses helpers"| node_common
node_track -->|"uses helpers"| node_common
node_inspect -->|"uses helpers"| node_common
node_single -->|"uses helpers"| node_common
node_gfp -->|"uses helpers"| node_common
node_timing -->|"uses helpers"| node_common
node_classify -->|"uses helpers"| node_common
node_export -->|"uses helpers"| node_common
node_split -->|"uses helpers"| node_common
node_tune -->|"uses helpers"| node_common

click node_config "https://github.com/tlobnow/ec_pipeline/blob/main/configs/btrack_config.json"
click node_split "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/split_nd2.py"
click node_load "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/01_load_nd2.py"
click node_timing "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/check_nd2_timing.py"
click node_segment "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/02_segment.py"
click node_track "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/03_track.py"
click node_inspect "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/04_inspect.py"
click node_single "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/05_single_cell.py"
click node_gfp "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/06_gfp_structures.py"
click node_tune "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/tune_gfp.py"
click node_export "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/export_cells_tif.py"
click node_classify "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/classify_cells.py"
click node_convpaint "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/train_convpaint.py"
click node_common "https://github.com/tlobnow/ec_pipeline/blob/main/scripts/common.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_config,node_split,node_load,node_timing toneBlue
class node_segment,node_track,node_inspect,node_single toneAmber
class node_gfp,node_tune,node_export,node_classify,node_convpaint toneMint
class node_common toneRose
class node_user,node_nd2 toneIndigo
```

## Components

### Acquisition

- [Experiment settings](https://github.com/tlobnow/ec_pipeline/blob/main/configs/btrack_config.json): `configs/btrack_config.json`
- [Split fields of view](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/split_nd2.py): `scripts/split_nd2.py`
- [Load channels](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/01_load_nd2.py): `scripts/01_load_nd2.py`
- [Inspect timing](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/check_nd2_timing.py): `scripts/check_nd2_timing.py`

### Cell Analysis

- [Segment cells](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/02_segment.py): `scripts/02_segment.py`
- [Track lineages](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/03_track.py): `scripts/03_track.py`
- [Inspect tracks](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/04_inspect.py): `scripts/04_inspect.py`
- [Follow cell lineage](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/05_single_cell.py): `scripts/05_single_cell.py`

### Phenotype Tools

- [Detect GFP structures](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/06_gfp_structures.py): `scripts/06_gfp_structures.py`
- [Tune GFP calls](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/tune_gfp.py): `scripts/tune_gfp.py`
- [Export cell images](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/export_cells_tif.py): `scripts/export_cells_tif.py`
- [Classify phenotypes](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/classify_cells.py): `scripts/classify_cells.py`
- [Train ConvPaint](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/train_convpaint.py): `scripts/train_convpaint.py`

### Shared Runtime

- [Shared helpers](https://github.com/tlobnow/ec_pipeline/blob/main/scripts/common.py): `scripts/common.py`

### Other components

- **Microscopy analyst**
- **ND2 experiment**

## Connections

- Microscopy analyst → Experiment settings: configures
- Microscopy analyst → ND2 experiment: selects input
- Split fields of view → ND2 experiment: splits fields (evidence: `scripts/split_nd2.py`)
- Load channels → ND2 experiment: reads images (evidence: `scripts/01_load_nd2.py`)
- Inspect timing → ND2 experiment: reads metadata (evidence: `scripts/check_nd2_timing.py`)
- Segment cells → Load channels: reads channel TIFF (evidence: `scripts/02_segment.py`)
- Inspect tracks → Load channels: reads channel TIFFs (evidence: `scripts/04_inspect.py`)
- Inspect tracks → Track lineages: reads tracked masks (evidence: `scripts/04_inspect.py`)
- Microscopy analyst → Split fields of view: runs
- Microscopy analyst → Load channels: runs
- Microscopy analyst → Segment cells: runs
- Microscopy analyst → Track lineages: runs
- Microscopy analyst → Inspect tracks: reviews
- Microscopy analyst → Follow cell lineage: selects cell
- Microscopy analyst → Detect GFP structures: analyzes
- Microscopy analyst → Tune GFP calls: tunes calls
- Microscopy analyst → Export cell images: exports cells
- Microscopy analyst → Classify phenotypes: trains or applies
- Microscopy analyst → Train ConvPaint: trains
- Load channels → Shared helpers: uses helpers (evidence: `scripts/01_load_nd2.py`)
- Segment cells → Shared helpers: uses helpers (evidence: `scripts/02_segment.py`)
- Track lineages → Shared helpers: uses helpers (evidence: `scripts/03_track.py`)
- Inspect tracks → Shared helpers: uses helpers (evidence: `scripts/04_inspect.py`)
- Follow cell lineage → Shared helpers: uses helpers (evidence: `scripts/05_single_cell.py`)
- Detect GFP structures → Shared helpers: uses helpers (evidence: `scripts/06_gfp_structures.py`)
- Inspect timing → Shared helpers: uses helpers (evidence: `scripts/check_nd2_timing.py`)
- Classify phenotypes → Shared helpers: uses helpers (evidence: `scripts/classify_cells.py`)
- Export cell images → Shared helpers: uses helpers (evidence: `scripts/export_cells_tif.py`)
- Split fields of view → Shared helpers: uses helpers (evidence: `scripts/split_nd2.py`)
- Tune GFP calls → Shared helpers: uses helpers (evidence: `scripts/tune_gfp.py`)
