MORPHӔUS is Python-based software for morphology-aware classification of single cells and multicellular tissue structures in whole-slide multiplex images of tissue using the variational autoencoder deep learning network architecture.

---

Installation

Install MORPHӔUS into a dedicated Conda environment and activate it with the following commands:

# macOS
conda create -n morphaeus -c conda-forge -c labsyspharm python=3.11 vae
conda activate morphaeus

# PC
conda create -n morphaeus python=3.11
conda activate morphaeus
pip install git+https://github.com/labsyspharm/vae.git@v0.0.7

If conda is not already installed, you can download it by following the instructions provided here.

---

Program Execution

Make a copy of the config.yml file in the vae folder of the installed MORPHӔUS Conda environment and modify all applicable paths and configuration settings. Run the program with the following command:

vae <path/to/config.yml>

The pipeline supports progress bookmarking, allowing the program to pick up where it left off between runs. Users may elect to re-run a particular module by adding the --module flag as follows:

vae --module <MODULE_NAME> <path/to/config.yml>

Available modules:

• GENERATE_CELLCUTTER_INPUT
• DETECT_ARTIFACTS (under development)
• RUN_CELLCUTTER
• GENERATE_IMAGE_GALLERY
• REMOVE_BACKGROUND
• TRAIN_VAE
• ENCODE_IMAGES
• SALIENCY_MAP

Note: In order to re-run a module, the corresponding checkpoint file must be removed from the checkpoints folder in the output directory.

---

MORPHӔUS Source Code

MORPHӔUS source code is freely-available for academic use and archived on Zenodo.

---

Funding Acknowledgments

This work was supported by Ludwig Cancer Research and the Ludwig Center at Harvard (P.K.S., S.S.), the Gray Foundation, and by NIH NCI grants U01-CA284207, and U2C-CA233262. S.S. is supported by the BWH President’s Scholars Award. Results shown in this study are in part based upon data generated by the Human Tumor Atlas Network (HTAN, https://humantumoratlas.org/).

---

References

Baker GJ., Novikov E. et al. Morphology-Aware Profiling of Highly Multiplexed Tissue Images using Variational Autoencoders. bioRxiv (2025) https://doi.org/10.1101/2025.06.23.661064