MorphCell

MorphCell is a point-cloud learning framework for three-dimensional cell morphology. The repository provides the model implementations, data loaders, Hydra configurations and training scripts used in the MorphCell study.

The paper is available on bioRxiv.

Installation

MorphCell uses uv to manage a reproducible Python 3.12 environment. The locked environment includes PyTorch 2.7.1 with CUDA 11.8 and the CUDA-based pointnet2-ops extension.

Requirements

• Python 3.12
• An NVIDIA GPU with a CUDA 11.8-compatible driver
• CUDA Toolkit 11.8, including nvcc
• A C/C++ compiler and Ninja

Install the build tools with:

sudo apt update
sudo apt install -y build-essential ninja-build

Install CUDA Toolkit 11.8 from the NVIDIA CUDA archive, then verify the installation:

nvcc --version

Install uv and create the environment from the repository root:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

Activate the environment and verify the main dependencies:

source .venv/bin/activate
python -c "import torch, pointnet2_ops, morphcell; print(torch.__version__)"

Datasets

Dataset preparation code and source information are available in the MorphCell-Datasets repository.

By default, MorphCell looks for data in datasets/ at the repository root. Set MORPHCELL_DATA_ROOT to use another location:

export MORPHCELL_DATA_ROOT=/absolute/path/to/datasets

Arrange the downloaded files as follows. This is the directory structure used by the supplied configurations:

datasets/
├── colon/
│   ├── metadata.json
│   ├── MEM/
│   │   └── mem.h5
│   └── NUC/
│       └── nuc.h5
├── intrA/
│   ├── metadata.json
│   └── set1/
│       └── intrA.h5
├── redblood/
│   ├── metadata.json
│   └── set1/
│       └── redblood.h5
├── wheat/
│   ├── metadata.json
│   └── set1/
│       └── wheat.h5
└── shapenet55-34/
    ├── pcl/
    │   ├── 02691156-1a04e3eab45ca15dd86060f189eb133.npy
    │   └── ...
    └── splits/
        └── ...

The biological point-cloud datasets are distributed as HDF5 files in the data repository. ShapeNet55-34 follows the structure provided by the Point-BERT dataset instructions.

Each biological dataset includes a metadata.json file that maps integer labels to class names:

{
  "label2name": {
    "0": "class_0",
    "1": "class_1"
  }
}

Training

Run training commands from the repository root after activating the uv environment. Four pretraining entry points are provided:

bash scripts/pretrain_dfn.sh
bash scripts/pretrain_direct+self.sh
bash scripts/pretrain_cross+self.sh
bash scripts/pretrain_cytodl_point.sh

Script	Configuration	Output directory
pretrain_dfn.sh	pretrain_dfn with a DGCNN encoder	outputs/pretrain/pretrain_dfn_dgcnn/
pretrain_direct+self.sh	direct reconstruction with self-supervision	outputs/pretrain/pretrain_direct+self/
pretrain_cross+self.sh	cross reconstruction with self-supervision	outputs/pretrain/pretrain_cross+self/
pretrain_cytodl_point.sh	point-based CytoDL pretraining	outputs/pretrain/pretrain_cytodl_point/

The DFN baseline is derived from CellShape. The point-based CytoDL baseline is derived from CytoDL.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International license. See LICENSE for details.