Sovereign 8s.is mirror of standardgalactic/iEHM-analysis
  • Jupyter Notebook 62.5%
  • Python 37.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-07-09 15:03:13 +02:00
notebooks Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00
src/iehm Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00
.gitignore Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00
LICENSE Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00
pyproject.toml Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00
README.md Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00
uv.lock Initial commit: iEHM image analysis pipeline 2026-07-09 15:03:13 +02:00

iEHM

Image analysis code used in the iEHM (innervated Engineered Human Myocardium) publication, "Innervated human cardiac muscle model reveals sympathetic drivers of KCNH2-associated arrhythmias" (accepted, Nature Communications). The pipeline segments vasculature and axons (neurofilament) in confocal microscopy stacks using two U-Net models, then quantifies the orientational correlation between the two networks.

Method

Segmentation + orientation analysis (notebooks/analysis.ipynb, src/iehm/analysis.py):

  1. Load a 4-channel confocal z-stack (.lsm): neurofilament (NF), vasculature/CD31 (VS), nuclei, pericytes/PDGFR.
  2. Maximum-intensity-project each channel along z (maxproj).
  3. Segment the NF and VS projections independently with two U-Nets (Unet_v0, trained separately per channel), tiled at 2048x2048 (predict_NF_VS).
  4. Threshold each mask at 0.5, skeletonize (skimage.morphology.skeletonize), and extract line segments with a probabilistic Hough transform (line_gap=50) (orientation_analysis).
  5. Convert each line segment to an orientation angle, bin into a 20-bin histogram per channel, and compute the Pearson correlation R between the VS and NF orientation histograms — the reported measure of vascular/axonal co-alignment.
  6. Render the figure panels (raw/mask/overlay images, orientation-colored skeletons, polar histogram) and save result.pdf (plot).

U-Net training (notebooks/training_data_generation.ipynb, notebooks/training.ipynb):

  1. For each of the 25 raw .lsm stacks, max-project and take one random 1024x1024 crop (fixed seed) per channel, saved separately for the NF and VS models.
  2. Each crop is hand-annotated with a binary segmentation mask (data/training/{NF,VS}/label/).
  3. DataProcess tiles each crop into 256x256 patches and augments them (aug_factor=10 copies per patch by default), applying, with an overall probability p=0.8:
    • RandomRotate90 — always
    • RandomBrightnessContrast — ±25%, p=0.5
    • Blur — kernel size 3–7, p=0.2
    • MultiplicativeNoise — 0.5x–1.2x, elementwise, p=0.3
    • shift/scale/rotation is disabled by default (shiftscalerotate=(0, 0, 0))
  4. Trainer fits a Unet_v0 (n_filter=32) for 100 epochs (BCEDice loss, Adam, ReduceLROnPlateau), saving the checkpoint with the best validation loss. These are the same defaults used to train the provided models/model_NF.pth and models/model_VS.pth.

Data Availability

All datasets are publicly available via Zenodo and are citable with permanent DOIs.

Dataset Description DOI
NF.7z Training data: Neurofilament (NF) images and labels DOI
VS.7z Training data: Vasculature (VS) images and labels DOI
test.7z Test data: 3 raw .lsm stacks for model evaluation DOI
publication_data.7z Raw data used in publication (full stacks) DOI
models.7z Models used in publication DOI

How to Use

Run notebooks/data_download.ipynb to download and extract all datasets. Data will be placed in:

  • data/training/NF/
  • data/training/VS/
  • data/test/
  • data/publication_data/
  • data/models/

Installation

Requires Python >= 3.9 and uv.

uv sync

This creates .venv and installs all dependencies pinned in uv.lock. To also install JupyterLab for running the notebooks:

uv sync --extra notebooks

Usage

These notebooks cover each step of the pipeline (paths inside them are relative to notebooks/):

  • notebooks/analysis.ipynb — main analysis: loads an .lsm stack, runs U-Net segmentation (iehm.iEHM_Analysis), computes orientation correlation, and produces the figure panels used in the publication. Points at data/test/ by default.
  • notebooks/training_data_generation.ipynb — generates random training crops for the segmentation U-Nets from the raw .lsm files in data/publication_data/. The crops already in data/training/{NF,VS}/image/ line up with the hand-drawn masks in data/training/{NF,VS}/label/; re-running it reshuffles crop positions and invalidates the existing labels (see the in-notebook warning).
  • notebooks/training.ipynb — trains the Unet_v0 NF/VS segmentation models on those crops and labels. Saves to models/retrained/ rather than overwriting the shipped models/model_NF.pth/model_VS.pth.

The core analysis code lives in src/iehm/analysis.py and is importable as iehm once the environment is set up (from iehm import iEHM_Analysis).

Directory layout

data/
  training/
    NF/{image,label}/            U-Net training crops for the axon (NF) model
    VS/{image,label}/            U-Net training crops for the vessel (VS) model
  test/                          3 example .lsm stacks for a quick pipeline run
  publication_data/              raw .lsm stacks used in the publication (from Zenodo)
  models/                        models used in the publication (from Zenodo)
models/
  model_NF.pth                   trained U-Net weights, axon segmentation
  model_VS.pth                   trained U-Net weights, vessel segmentation
notebooks/                       analysis and training notebooks (see above)
src/iehm/                        installable analysis package

Notes on the data

  • models/model_NF.pth/model_VS.pth were saved with an in_channels key but no out_channels key, which bio-image-unet>=1.1.2 requires for the Unet_v0 architecture. Both checkpoints were patched in place to add out_channels=1 (the state dict / weights are untouched) so notebooks/analysis.ipynb runs end-to-end.

License

MIT — see LICENSE.