# segevmunitz/astrocytes_morphology_detection architecture

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

- Interactive diagram: https://gitdiagram.com/segevmunitz/astrocytes_morphology_detection
- Repository: https://github.com/segevmunitz/astrocytes_morphology_detection

## Overview

AstroSeg builds complete GFAP-positive astrocyte instances from microscopy, linking each predicted cell’s nucleus, soma, and processes. The principal path prepares manifest-backed images and annotations, trains a multi-head model, predicts image patches, then reconstructs individual cells and measurements/QC. Separate branches support human mask import/review, pseudo-labeling, the older semantic/binary pipeline, and Cellpose refinement. Edges are limited to README statements and shown source references/calls; unsampled implementation details are not inferred.

Main entry points: [`src/astroseg/inference/predict_instances.py`](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/inference/predict_instances.py) (Patch inference), [`src/astroseg/training/instance_trainer.py`](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/instance_trainer.py) (Instance trainer), [`src/astroseg/datasets/instance_dataset.py`](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/datasets/instance_dataset.py) (Instance patches), [`src/astroseg/annotations/workflow.py`](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/workflow.py) (Mask import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_manifest["Manifest schema<br/>[manifest.py]"]
  node_imageio["Microscopy I/O<br/>[ome_tiff.py]"]
  node_channels["Channel selection<br/>[channels.py]"]
  node_instancedata["Instance patches"]
  node_targets["Instance targets"]
  node_dataset["Semantic patches"]
end

subgraph group_learning["Model training"]
  node_trainer["Instance trainer"]
  node_model["Multichannel U-Net"]
  node_losses["Training losses<br/>[losses.py]"]
  node_checkpoints["Checkpoints<br/>[checkpoints.py]"]
end

subgraph group_prediction["Instance prediction"]
  node_inference["Patch inference"]
  node_reconstruction["Cell reconstruction"]
  node_nuclei["Nucleus detection"]
  node_skeleton["Cell morphology<br/>[skeleton.py]"]
  node_analysis["Image measurements<br/>[morphology.py]"]
  node_overlays["QC overlays<br/>[overlays.py]"]
end

subgraph group_annotation["Annotation workflows"]
  node_annotation_import["Mask import<br/>[workflow.py]"]
  node_annotation_instance["Instance annotation workflow"]
  node_review["Mask review GUI<br/>[mask_review.py]"]
  node_pseudo["Pseudo-labeling<br/>[pseudo_labels.py]"]
end

subgraph group_alternatives["Other model paths"]
  node_legacy["Binary U-Net<br/>[unet.py]"]
  node_cellpose["Cellpose transfer<br/>[transfer.py]"]
  node_cellpose_model["Cellpose model"]
end

node_scientist(("Microscopy user"))
node_store[("Dataset artifacts")]
node_results["Instance results"]

node_scientist -->|"defines dataset"| node_manifest
node_manifest -->|"indexes samples"| node_instancedata
node_instancedata -->|"loads images"| node_imageio
node_instancedata -->|"builds targets"| node_targets
node_instancedata -->|"prepares channels"| node_channels
node_scientist -->|"trains model"| node_trainer
node_trainer -->|"optimizes"| node_model
node_trainer -->|"computes loss"| node_losses
node_trainer -->|"saves weights"| node_checkpoints
node_trainer -.->|"consumes batches"| node_instancedata
node_model -.->|"predicts heads"| node_inference
node_inference -.->|"uses nuclei"| node_nuclei
node_inference -.->|"reconstructs cells"| node_reconstruction
node_scientist -->|"predicts images"| node_inference
node_inference -.->|"loads weights"| node_checkpoints
node_inference -->|"writes predictions"| node_results
node_reconstruction -->|"labels instances"| node_results
node_reconstruction -.->|"derives morphology"| node_skeleton
node_analysis -->|"uses skeleton"| node_skeleton
node_scientist -->|"imports masks"| node_annotation_import
node_annotation_import -->|"loads microscopy"| node_imageio
node_annotation_import -->|"creates QC overlay"| node_overlays
node_scientist -->|"reviews masks"| node_review
node_annotation_instance -->|"uses import workflow"| node_annotation_import
node_scientist -->|"creates pseudo-labels"| node_pseudo
node_scientist -->|"runs baseline"| node_legacy
node_scientist -->|"refines Cellpose"| node_cellpose
node_cellpose -.->|"transfers weights"| node_cellpose_model
node_dataset -->|"loads images"| node_imageio
node_dataset -->|"prepares inputs"| node_channels
node_scientist -->|"stores artifacts"| node_store
node_results -->|"persists outputs"| node_store

click node_manifest "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/io/manifest.py"
click node_imageio "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/io/ome_tiff.py"
click node_channels "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/preprocessing/channels.py"
click node_instancedata "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/datasets/instance_dataset.py"
click node_targets "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/preprocessing/instance_targets.py"
click node_dataset "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/datasets/astrocyte_dataset.py"
click node_trainer "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/instance_trainer.py"
click node_model "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/models/multichannel_unet.py"
click node_losses "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/losses.py"
click node_checkpoints "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/checkpoints.py"
click node_inference "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/inference/predict_instances.py"
click node_reconstruction "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/postprocessing/astrocyte_instances.py"
click node_nuclei "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/preprocessing/nucleus_detection.py"
click node_skeleton "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/postprocessing/skeleton.py"
click node_analysis "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/analysis/morphology.py"
click node_overlays "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/visualization/overlays.py"
click node_annotation_import "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/workflow.py"
click node_annotation_instance "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/instance_workflow.py"
click node_review "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/gui/mask_review.py"
click node_pseudo "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/pseudo_labels.py"
click node_legacy "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/models/unet.py"
click node_cellpose "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/cellpose/transfer.py"
click node_cellpose_model "https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/models/cellpose_transfer.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_manifest,node_imageio,node_channels,node_instancedata,node_targets,node_dataset,node_scientist toneBlue
class node_trainer,node_model,node_losses,node_checkpoints,node_store toneAmber
class node_inference,node_reconstruction,node_nuclei,node_skeleton,node_analysis,node_overlays toneMint
class node_annotation_import,node_annotation_instance,node_review,node_pseudo toneRose
class node_legacy,node_cellpose,node_cellpose_model,node_results toneIndigo
```

## Components

### Data preparation

- [Manifest schema](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/io/manifest.py): `src/astroseg/io/manifest.py`
- [Microscopy I/O](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/io/ome_tiff.py): `src/astroseg/io/ome_tiff.py`
- [Channel selection](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/preprocessing/channels.py): `src/astroseg/preprocessing/channels.py`
- [Instance patches](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/datasets/instance_dataset.py): `src/astroseg/datasets/instance_dataset.py`
- [Instance targets](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/preprocessing/instance_targets.py): `src/astroseg/preprocessing/instance_targets.py`
- [Semantic patches](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/datasets/astrocyte_dataset.py): `src/astroseg/datasets/astrocyte_dataset.py`

### Model training

- [Instance trainer](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/instance_trainer.py): `src/astroseg/training/instance_trainer.py`
- [Multichannel U-Net](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/models/multichannel_unet.py): `src/astroseg/models/multichannel_unet.py`
- [Training losses](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/losses.py): `src/astroseg/training/losses.py`
- [Checkpoints](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/training/checkpoints.py): `src/astroseg/training/checkpoints.py`

### Instance prediction

- [Patch inference](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/inference/predict_instances.py): `src/astroseg/inference/predict_instances.py`
- [Cell reconstruction](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/postprocessing/astrocyte_instances.py): `src/astroseg/postprocessing/astrocyte_instances.py`
- [Nucleus detection](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/preprocessing/nucleus_detection.py): `src/astroseg/preprocessing/nucleus_detection.py`
- [Cell morphology](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/postprocessing/skeleton.py): `src/astroseg/postprocessing/skeleton.py`
- [Image measurements](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/analysis/morphology.py): `src/astroseg/analysis/morphology.py`
- [QC overlays](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/visualization/overlays.py): `src/astroseg/visualization/overlays.py`

### Annotation workflows

- [Mask import](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/workflow.py): `src/astroseg/annotations/workflow.py`
- [Instance annotation workflow](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/instance_workflow.py): `src/astroseg/annotations/instance_workflow.py`
- [Mask review GUI](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/gui/mask_review.py): `src/astroseg/gui/mask_review.py`
- [Pseudo-labeling](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/annotations/pseudo_labels.py): `src/astroseg/annotations/pseudo_labels.py`

### Other model paths

- [Binary U-Net](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/models/unet.py): `src/astroseg/models/unet.py`
- [Cellpose transfer](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/cellpose/transfer.py): `src/astroseg/cellpose/transfer.py`
- [Cellpose model](https://github.com/segevmunitz/astrocytes_morphology_detection/blob/main/src/astroseg/models/cellpose_transfer.py): `src/astroseg/models/cellpose_transfer.py`

### Other components

- **Microscopy user**
- **Dataset artifacts**
- **Instance results**

## Connections

- Microscopy user → Manifest schema: defines dataset (evidence: `README.md`)
- Manifest schema → Instance patches: indexes samples (evidence: `src/astroseg/datasets/instance_dataset.py`)
- Instance patches → Microscopy I/O: loads images (evidence: `src/astroseg/datasets/instance_dataset.py`)
- Instance patches → Instance targets: builds targets (evidence: `src/astroseg/datasets/instance_dataset.py`)
- Instance patches → Channel selection: prepares channels
- Microscopy user → Instance trainer: trains model (evidence: `README.md`)
- Instance trainer → Multichannel U-Net: optimizes (evidence: `src/astroseg/training/instance_trainer.py`)
- Instance trainer → Training losses: computes loss (evidence: `src/astroseg/training/instance_trainer.py`)
- Instance trainer → Checkpoints: saves weights (evidence: `src/astroseg/training/instance_trainer.py`)
- Instance trainer → Instance patches: consumes batches
- Multichannel U-Net → Patch inference: predicts heads
- Patch inference → Nucleus detection: uses nuclei
- Patch inference → Cell reconstruction: reconstructs cells
- Microscopy user → Patch inference: predicts images (evidence: `README.md`)
- Patch inference → Checkpoints: loads weights
- Patch inference → Instance results: writes predictions (evidence: `README.md`)
- Cell reconstruction → Instance results: labels instances (evidence: `README.md`)
- Cell reconstruction → Cell morphology: derives morphology
- Image measurements → Cell morphology: uses skeleton (evidence: `src/astroseg/analysis/morphology.py`)
- Microscopy user → Mask import: imports masks (evidence: `README.md`)
- Mask import → Microscopy I/O: loads microscopy (evidence: `src/astroseg/annotations/workflow.py`)
- Mask import → QC overlays: creates QC overlay (evidence: `src/astroseg/annotations/workflow.py`)
- Microscopy user → Mask review GUI: reviews masks (evidence: `README.md`)
- Instance annotation workflow → Mask import: uses import workflow (evidence: `src/astroseg/annotations/instance_workflow.py`)
- Microscopy user → Pseudo-labeling: creates pseudo-labels (evidence: `README.md`)
- Microscopy user → Binary U-Net: runs baseline (evidence: `README.md`)
- Microscopy user → Cellpose transfer: refines Cellpose (evidence: `README.md`)
- Cellpose transfer → Cellpose model: transfers weights
- Semantic patches → Microscopy I/O: loads images (evidence: `src/astroseg/datasets/astrocyte_dataset.py`)
- Semantic patches → Channel selection: prepares inputs (evidence: `src/astroseg/datasets/astrocyte_dataset.py`)
- Microscopy user → Dataset artifacts: stores artifacts (evidence: `README.md`)
- Instance results → Dataset artifacts: persists outputs (evidence: `README.md`)