MorphoDeep

MorphoDeep segments individual cells in grayscale microscopy images of membranes. It supports 2D images and 3D volumes and returns an integer label image: 0 is background, and each positive value identifies one cell. The package provides a command-line interface, a Python API, and napari widgets for prediction and fine tuning.

Install

MorphoDeep 0.1 supports Python 3.10 and 3.11. Install the library with:

python -m pip install morphodeep

To use the napari widgets, install the optional graphical dependencies:

python -m pip install 'morphodeep[napari]'

TensorFlow 2.15 is installed as a package dependency. GPU setup depends on the operating system and hardware; consult the TensorFlow installation guide if GPU support is needed.

Predict cell instances

Pass a grayscale TIFF image or volume to the command-line tool:

morphodeep predict image.tif image_instances.tif --mode 2D
morphodeep predict volume.tif volume_instances.tif --mode 3D --size 128

The dimension can be inferred from the TIFF file. The default model size is 256 in 2D and 128 in 3D; a 256 model is also available in 3D. Predictions use overlapping patches by default. Use --no-patches for whole-image inference, --weights path/to/model.h5 for custom weights, and --overwrite to replace an output file.

In Python:

from morphodeep.napari.model import run_instance_segmentation

labels = run_instance_segmentation(image, mode="2D", net_size=256)

The result has the same shape as the input and contains integer instance labels.

Pretrained weights

The three pretrained models are hosted separately in the MorphoDeep weights dataset on Figshare:

MorphoDeep downloads the selected file on first use, verifies its SHA-256 digest, and caches it for later offline use. The weights are not included in the Python package. To use files already on disk, pass --weights to prediction or set MORPHODEEP_WEIGHTS_DIR to a directory containing the published filenames, either directly or under 2D/ and 3D/ subdirectories.

Fine tune on your own data

Provide grayscale TIFF images and corresponding instance masks in separate directories. Files are paired by name before the extension, and images and masks must have the same shape. In each mask, 0 is background and each positive integer identifies one cell.

morphodeep finetune --images data/images --masks data/masks \
  --output runs/my_cells --mode 2D --epochs 20

Use --mode 3D for volumes. At least two image and mask pairs are required. By default, whole images are split reproducibly into training and validation sets. Related images, such as slices from the same volume, should use independent validation directories via --validation-images and --validation-masks. The best weights are written to runs/my_cells/best.weights.h5 and can be used for prediction:

morphodeep predict image.tif image_instances.tif \
  --weights runs/my_cells/best.weights.h5

Fine tuning is also available through morphodeep.training.fine_tune and the Fine tune model napari widget. The Predict instances widget accepts the resulting file in its Custom weights field.

Documentation and research code

The docs/ directory contains installation, prediction, fine-tuning, napari, and Python API guides. From a source checkout, build the documentation with:

python -m pip install -e '.[docs]'
python -m mkdocs build --strict

The historical training and data preparation workflow is documented in docs/research/legacy_training.md. It is separate from the supported morphodeep finetune command and may require research-cluster resources.

Source and issues

The source code and issue tracker are on Codeberg. Read the full documentation for the installation guide, examples, and Python API.

License

MorphoDeep is distributed under the GNU LGPL v3.0 license. The Figshare weights dataset has its own CC BY 4.0 license.