- Jupyter Notebook 62.5%
- Python 37.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| notebooks | ||
| src/iehm | ||
| .gitignore | ||
| LICENSE | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
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):
- Load a 4-channel confocal z-stack (
.lsm): neurofilament (NF), vasculature/CD31 (VS), nuclei, pericytes/PDGFR. - Maximum-intensity-project each channel along z (
maxproj). - Segment the NF and VS projections independently with two U-Nets
(
Unet_v0, trained separately per channel), tiled at 2048x2048 (predict_NF_VS). - Threshold each mask at 0.5, skeletonize
(
skimage.morphology.skeletonize), and extract line segments with a probabilistic Hough transform (line_gap=50) (orientation_analysis). - Convert each line segment to an orientation angle, bin into a 20-bin
histogram per channel, and compute the Pearson correlation
Rbetween the VS and NF orientation histograms — the reported measure of vascular/axonal co-alignment. - 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):
- For each of the 25 raw
.lsmstacks, max-project and take one random 1024x1024 crop (fixed seed) per channel, saved separately for the NF and VS models. - Each crop is hand-annotated with a binary segmentation mask
(
data/training/{NF,VS}/label/). DataProcesstiles each crop into 256x256 patches and augments them (aug_factor=10copies per patch by default), applying, with an overall probability p=0.8:RandomRotate90— alwaysRandomBrightnessContrast— ±25%, p=0.5Blur— kernel size 3–7, p=0.2MultiplicativeNoise— 0.5x–1.2x, elementwise, p=0.3- shift/scale/rotation is disabled by default
(
shiftscalerotate=(0, 0, 0))
Trainerfits aUnet_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 providedmodels/model_NF.pthandmodels/model_VS.pth.
Data Availability
All datasets are publicly available via Zenodo and are citable with permanent DOIs.
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.lsmstack, runs U-Net segmentation (iehm.iEHM_Analysis), computes orientation correlation, and produces the figure panels used in the publication. Points atdata/test/by default.notebooks/training_data_generation.ipynb— generates random training crops for the segmentation U-Nets from the raw.lsmfiles indata/publication_data/. The crops already indata/training/{NF,VS}/image/line up with the hand-drawn masks indata/training/{NF,VS}/label/; re-running it reshuffles crop positions and invalidates the existing labels (see the in-notebook warning).notebooks/training.ipynb— trains theUnet_v0NF/VS segmentation models on those crops and labels. Saves tomodels/retrained/rather than overwriting the shippedmodels/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.pthwere saved with anin_channelskey but noout_channelskey, whichbio-image-unet>=1.1.2requires for theUnet_v0architecture. Both checkpoints were patched in place to addout_channels=1(the state dict / weights are untouched) sonotebooks/analysis.ipynbruns end-to-end.
License
MIT — see LICENSE.