CTransformer

English | 简体中文

Deep-transformer-based 3D cell membrane tracking with subcellular-resolved molecular quantification.

This repository implements the core CTransformer pipeline, including:

• TUNETr: 3D/4D membrane segmentation with topology-constrained training
• MolQuantifier: cell morphology and contact-interface quantification
• GUI data generation for ITK-SNAP-CVE

The membrane-to-pseudo-nucleus module m2nGAN is maintained in a separate repository: https://github.com/chiellini/m2nGAN

Manual style and workflow presentation are inspired by CMap: https://github.com/chiellini/CMap

Contents

• 1. Overview
• 2. Repository structure
• 3. Script map (1 to 8)
• 4. Quick start
• 5. Data layout convention
• 6. Module mapping
• 7. Common pitfalls
• 8. Links
• 9. License

---

1. Overview

1.1 One-line summary

CTransformer builds 4D embryonic cell morphology maps from membrane channels and supports downstream lineage tracing and molecular quantification.

1.2 Main pipeline

flowchart LR
    A[RawMemb 4D stacks] --> B[TUNETr / iTUNETr / sTUNETr / 4dTUNETr]
    B --> C[SegMemb]
    C --> D[SegCell instance]
    D --> E[Cell identity reassignment]
    E --> F[Morphology + Contact Quantification]
    F --> G[GUI-ready data for ITK-SNAP-CVE]
    D -. optional .-> H[m2nGAN repo]
    H -. pseudo nuclei .-> I[Lineage tracing tools]

Loading

1.3 Core capabilities

• Multiple backbones: UNet, VNet, DMFNet, UNETR, SwinUNETR, ParallelSwinUNETR
• Training modes: supervised, 4D, topology-constrained, semi-supervised
• Evaluation: membrane metrics + cell-instance metrics (Dice/Jaccard/HD)
• Downstream analysis: volume, surface area, cell-cell contact area, aggregated morphology stats

---

2. Repository structure

CTransformer/
├─ 1_*.py ~ 8_*.py               # Main workflow scripts (train/validate/infer/postprocess/quantify/GUI)
├─ run_segmentation.py           # Legacy all-in-one inference script
├─ preprocess_script.py          # Data preprocessing helper
├─ calculate_quantitively.py     # Quantification-related utility script
├─ put_apoptotic_cells.py        # Apoptotic cell related processing
├─ data_utils/                   # Dataset definitions, augmentation, sampling, transforms
├─ networks/                     # Segmentation models (UNet/VNet/DMFNet/UNETR/SwinUNETR)
├─ segmentation_utils/           # Inference and instance-segmentation post-processing
├─ train_utils/                  # Losses, training visualization, validation, topology functions
├─ lineage_gui_utils/            # Lineage tree and GUI data generation
├─ utils/                        # IO, morphology helpers, NIfTI dataset tools
├─ para_config/                  # YAML config center (train/validate/infer)
├─ tem_important_files/          # Temporary/important dictionaries and materials
├─ *.ipynb                       # Topological loss and exploratory notebooks
├─ environment.yml               # Environment dependencies (CUDA + PyTorch + bioimage stack)
└─ SBATCH_submit_script.sh       # Cluster submission sample

---

3. Script map (1 to 8)

Stage	Script	Purpose
1	1_train_segmentation.py	3D supervised training
1-4D	1_4D_train_segmentation.py	4D context training
2.5	2_5_validate_segmentation.py	Training-time validation (membrane + cell)
3	3_test_segmentation.py	Test-set inference
3	3_run_segmentation.py	Running-set inference with optional instance segmentation
4	4_train_topologically.py	Topology-constrained training
4	4_train_enhancement.py	Enhanced topology training
4	4_train_enhancement_trying_mp.py	Multi-process enhanced training attempt
4	4_semi_train_segmentation.py	Semi-supervised training
5	5_validate_semi_supervised_topologically.py	Semi-supervised/topological validation and threshold sweep
6	6_build_cell_shape_map.py	Cell identity reassignment (align SegCell to biological names)
7	7_cell_morphological_analysis.py	Volume/surface/contact quantification
8	8_generate_gui_data.py	GUI data generation (cell-wise / fate-wise)

Notes:

• 6/7/8 also have for_app variants for CellAppData layout.
• run_segmentation.py is kept for compatibility and reference.

---

4. Quick start

4.1 Environment

conda env create -f environment.yml
conda activate CellUNetr

Recommended:

• Linux + CUDA GPU (scripts are GPU-oriented)
• Python 3.9 (see environment.yml)

4.2 Configuration

All main scripts load YAML through -cfg/--cfg (parsed and merged by para_config/parser.py).

Common naming patterns:

• 1_*_TRAIN.yaml: training
• 2_*_VALIDATE.yaml: validation
• 3_*_running*.yaml: inference
• 4_* / 5_*: topology and semi-supervised workflows

4.3 Minimal runnable flow

# 1) Train (example: 3DUNet)
python 1_train_segmentation.py -cfg para_config/1_3DUNet_TRAIN.yaml -gpu 0

# 2) Validate (example: 3DUNet)
python 2_5_validate_segmentation.py -cfg para_config/2_3DUNet_VALIDATE.yaml -gpu 0

# 3) Run inference (example: TUNETr running config)
python 3_run_segmentation.py -cfg para_config/3_TUNETr_running_iTUNETr.yaml -gpu 0

Topology training example:

python 4_train_topologically.py -cfg para_config/1_1_TUNETr_Topologically_TRAIN.yaml --logging_suffix topo -gpu 0

---

5. Data layout convention

Core directory pattern expected by scripts:

<root>/
└─ <embryo_name>/
   ├─ RawMemb/
   │  └─ <embryo>_<tp>_rawMemb.nii.gz
   ├─ RawNuc/                       # needed only for specific workflows
   │  └─ <embryo>_<tp>_rawNuc.nii.gz
   ├─ SegMemb/                      # inference output
   ├─ SegCell/                      # instance-segmentation output
   └─ ...                           # CD files, stats files, etc.

Common output locations:

• ./ckpts/<net>/: checkpoints and config snapshots
• ./OutputData/.../SegMemb: membrane segmentation results
• Cell-map/stats outputs: written by scripts 6/7/8 according to configured paths

---

6. Module mapping

6.1 TUNETr (this repository)

• Training entry: 1_*, 4_*
• Validation entry: 2_5_*, 5_*
• Inference entry: 3_*

6.2 m2nGAN (external repository)

• URL: https://github.com/chiellini/m2nGAN
• Input: cell morphology/segmentation outputs from this repository
• Output: pseudo-nucleus images for downstream lineage tracing

6.3 MolQuantifier (this repository)

• Entry scripts: 6_*, 7_*, 8_*
• Output: cell-level and contact-level statistics + GUI visualization data

---

7. Common pitfalls

• -gpu defaults are list-style in some scripts; use -gpu 0 (single-card) unless your config/script expects another format.
• Scripts 6/7/8 contain hard-coded sample paths; replace them with local paths before running.
• net in YAML must match exported names in networks/__init__.py.
• NIfTI naming and timepoint formatting (e.g., 001) must be consistent, otherwise dataset loaders will miss files.

---

8. Links

• CTransformer data and software package (Figshare DOI)
  https://doi.org/10.6084/m9.figshare.27085657

• m2nGAN repository
  https://github.com/chiellini/m2nGAN

• CMap repository (manual layout reference)
  https://github.com/chiellini/CMap

---

9. License

MIT License. See LICENSE.