# fish-quant/rna2seg architecture

> Architecture diagram of the GitHub repository fish-quant/rna2seg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fish-quant/rna2seg
- Repository: https://github.com/fish-quant/rna2seg

## Overview

##### Project type and purpose
- RNA2seg is a Python library/package for deep-learning based cell segmentation in image-based spatial transcriptomics.
- It provides core modules for data ingestion (Zarr datasets + spatial RNA data via SpatialData), model definition (a CI-UNet), training scripts, utilities, logging, plus Jupyter notebooks and Sphinx-based documentation.

##### File structure
Top level:
- src/rna2seg/      ← core library
- docs/             ← Sphinx documentation sources and build artifacts
- img/              ← logos and overview images
- test/             ← unit tests
- pyproject.toml, requirements.txt, readthedocs.yml ← packaging & CI

Inside src/rna2seg/:
- dataset_zarr/     ← classes for loading Zarr datasets, background removal, augmentation, patching, staining/RNA transforms
- ci_unet.py        ← definition of the convolutional–involution UNet model
- models.py         ← higher-level model wrappers or alternate architectures
- train.py          ← training orchestration: hyperparameters, data pipeline, model instantiation, optimizer, callbacks
- logger.py         ← experiment logging (console, file, maybe wandb/tensorboard)
- utils.py          ← helper functions (I/O, transforms, etc)
- __init__.py       ← package exports

##### README for additional insights
- Highlights multi-channel inputs (nuclear, membrane, RNA)
- Leverages SpatialData for handling spatial transcriptomics formats
- Provides zero-shot inference notebooks: apply_model_on_crops.ipynb, apply_model_on_zarr.ipynb, train_model_on_zarr.ipynb

##### Elements
- Blue for core logic (src/rna2seg)
- Green for data (dataset_zarr)
- Orange for model & training
- Purple for docs & notebooks

##### Detailed capture of essential architectural elements
- CI/CD (readthedocs build, pytest) as a side pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    Zarr["Zarr"]:::external
    SpatialData["SpatialData"]:::external
    PyTorch["PyTorch"]:::external
    Sphinx["Sphinx (& nbsphinx)"]:::external
    pytest["pytest"]:::external

    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        direction TB
        RawData["Raw Spatial Transcriptomics Files"]:::data
        RNA2segDataset["RNA2segDataset"]:::data
        background["Background Removal"]:::data
        consistency["Consistency Checks"]:::data
        data_aug["Data Augmentation"]:::data
        patches["Patch Extraction"]:::data
        stain["Staining & RNA Transforms"]:::data
        DZUtils["Dataset Utils"]:::data
    end

    %% Core Model Definition
    subgraph "Model Definition"
        direction TB
        CIUnet["CI_UNet Architecture"]:::model
        AltModels["Alternate Models"]:::model
    end

    %% Training Orchestration
    subgraph "Training Orchestration"
        direction TB
        Train["train.py"]:::training
        Logger["Logger"]:::logging
        Checkpoints["Model Checkpoints"]:::training
    end

    %% Utilities & Constants
    subgraph "Utilities & Constants"
        direction TB
        Utils["General Utilities"]:::core
        Constants["Constants"]:::core
    end

    %% Inference / Notebook Interfaces
    subgraph "Inference Notebooks"
        direction TB
        CropNB["apply_model_on_crops.ipynb"]:::notebook
        ZarrNB["apply_model_on_zarr.ipynb"]:::notebook
        TrainNB["train_model_on_zarr.ipynb"]:::notebook
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocsSrc["Sphinx Source (docs/source/)"]:::docs
        DocsBuild["Build Artifacts (docs/build/)"]:::docs
    end

    %% Testing
    subgraph "Unit Testing"
        direction TB
        TestDS["test_dataset.py"]:::test
        TestTGT["test_target.py"]:::test
        TestConst["_constant_path.py"]:::test
    end

    %% Packaging & CI
    subgraph "Packaging & CI Configuration"
        direction TB
        PyProj["pyproject.toml"]:::ci
        Req["requirements.txt"]:::ci
        Readthedocs["readthedocs.yml"]:::ci
    end

    %% Data Flow Arrows
    RawData -->|"load via Zarr & SpatialData"| RNA2segDataset
    Zarr --> RNA2segDataset
    SpatialData --> RNA2segDataset
    RNA2segDataset --> background --> consistency --> data_aug --> patches --> stain --> Batch["TensorBatch"]:::data
    Batch --> CIUnet
    CIUnet --> Prediction["Prediction Masks"]:::model
    Prediction --> Post["Optional Post-processing"]:::model

    %% Training Flow
    Train -->|"uses Data & Model"| Batch
    Train --> CIUnet
    Train --> Logger
    Logger --> Checkpoints

    %% Notebook Interfaces
    CropNB --> RNA2segDataset
    CropNB --> CIUnet
    ZarrNB --> RNA2segDataset
    ZarrNB --> CIUnet
    TrainNB --> Train

    %% Documentation & Testing Pipelines
    DocsSrc --> DocsBuild
    Readthedocs --> DocsBuild
    TestDS --> Utils
    TestDS --> RNA2segDataset
    TestTGT --> CIUnet
    TestConst --> Constants
    pytest --> TestDS
    pytest --> TestTGT
    pytest --> TestConst

    %% Packaging
    PyProj -.->|"defines package"| Utils
    PyProj -.-> Constants
    Req -.-> Train
    Req -.-> CIUnet

    %% External Tools
    Sphinx --> DocsSrc

    %% Click Events
    click RNA2segDataset "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/dataset_zarr/RNA2segDataset.py"
    click background "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/dataset_zarr/background.py"
    click consistency "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/dataset_zarr/consistency.py"
    click data_aug "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/dataset_zarr/data_augmentation.py"
    click patches "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/dataset_zarr/patches.py"
    click stain "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/dataset_zarr/staining_transcript.py"
    click DZUtils "https://github.com/fish-quant/rna2seg/tree/main/src/rna2seg/dataset_zarr/utils/"
    click CIUnet "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/ci_unet.py"
    click AltModels "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/models.py"
    click Train "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/train.py"
    click Logger "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/logger.py"
    click Utils "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/utils.py"
    click Constants "https://github.com/fish-quant/rna2seg/blob/main/src/rna2seg/_constant.py"
    click CropNB "https://github.com/fish-quant/rna2seg/blob/main/docs/source/notebook/apply_model_on_crops.ipynb"
    click ZarrNB "https://github.com/fish-quant/rna2seg/blob/main/docs/source/notebook/apply_model_on_zarr.ipynb"
    click TrainNB "https://github.com/fish-quant/rna2seg/blob/main/docs/source/notebook/train_model_on_zarr.ipynb"
    click DocsSrc "https://github.com/fish-quant/rna2seg/tree/main/docs/source/"
    click DocsBuild "https://github.com/fish-quant/rna2seg/tree/main/docs/build/"
    click TestDS "https://github.com/fish-quant/rna2seg/blob/main/test/test_dataset.py"
    click TestTGT "https://github.com/fish-quant/rna2seg/blob/main/test/test_target.py"
    click TestConst "https://github.com/fish-quant/rna2seg/blob/main/test/_constant_path.py"
    click PyProj "https://github.com/fish-quant/rna2seg/blob/main/pyproject.toml"
    click Req "https://github.com/fish-quant/rna2seg/blob/main/requirements.txt"
    click Readthedocs "https://github.com/fish-quant/rna2seg/blob/main/readthedocs.yml"

    %% Styles
    classDef data fill:#D5F5E3,stroke:#27AE60,color:#145A32
    classDef model fill:#FCF3CF,stroke:#E67E22,color:#BA4A00
    classDef training fill:#FDEBD0,stroke:#F39C12,color:#7E5109
    classDef logging fill:#FDEBD0,stroke:#F39C12,color:#7E5109
    classDef core fill:#D6EAF8,stroke:#3498DB,color:#1B4F72
    classDef notebook fill:#E8DAEF,stroke:#8E44AD,color:#512E5F
    classDef docs fill:#E8DAEF,stroke:#8E44AD,color:#512E5F
    classDef test fill:#F5EEF8,stroke:#AF7AC5,color:#512E5F
    classDef ci fill:#F4F6F7,stroke:#95A5A6,color:#2C3E50
    classDef external fill:#F4F6F7,stroke:#95A5A6,color:#566573
```
