README.md

Nimbus Inference

Nimbus is a deep learning model for automated classification of marker expression in multiplexed imaging data. This repository provides code for:

• Inference of the Nimbus model on your multiplexed images.
• Finetuning the Nimbus model on new data if desired.
• Interactive exploration of the Nimbus Gold Standard dataset.

The code for training the Nimbus model from scratch can be found in the angelolab/Nimbus repository

Installation (via pip)

pip install Nimbus-Inference

Create a Python environment with version 3.9–3.11, then install as shown above.

---

Example Notebooks

We provide three Jupyter notebooks (in the templates folder), each with its own example dataset that is loaded from the Hugging Face Hub within the notebook:

• 1_Nimbus_Predict.ipynb

  • Guides you through performing inference with the Nimbus model on multiplexed imaging data.
  • 

• 2_Nimbus_Finetuning.ipynb

  • Shows you how to finetune the Nimbus model on a new dataset.
  • 

• 3_interactive_viewer.ipynb

  • Lets you interactively explore the Nimbus Gold Standard labeled dataset.
  • 

Each notebook loads an example dataset directly from the Hugging Face Hub, so you can get hands-on with Nimbus right away.

---

Datasets

We have released two main datasets on the Hugging Face Hub:

1. Pan-Multiplex

   • A large, noisy labeled dataset used for training and validation.
   • https://huggingface.co/datasets/JLrumberger/Pan-Multiplex

2. Pan-Multiplex Gold-Standard

   • A smaller subset of Pan-Multiplex where every cell was manually annotated by experts.
   • https://huggingface.co/datasets/JLrumberger/Pan-Multiplex-Gold-Standard

---

What is Nimbus?

Nimbus is a deep learning model designed to make human-like, visual classifications of multiplexed imaging data by determining which protein markers each cell is positive or negative for. Unlike many existing workflows, Nimbus:

• Uses the raw image pixels (rather than purely integrated intensity) to classify marker expression.
• Generalizes across many tissue types, imaging platforms, and markers — without retraining.
• Can be integrated into downstream clustering or phenotyping pipelines to improve accuracy.

For more details, please see our preprint.

---

Repository organization

Our github is organized as follows:

• The README file (which you're looking at now) provides an overview of the project
• The .github folder contains code automating jobs via github actions for testing and deployment
• The assets folder contains images that are displayed in the README
• The docs folder allows us to build and maintain updated documentation for the project
• The src folder contains the core code for running Nimbus
• The templates folder contains example notebooks to provide easy starting examples for new users
• The tests folder contains code for testing the codebase

For a more detailed look on how to get started, please check out our documentation

---

Contact

If you have questions, find a bug, or need help:

• Please use the issue tracker.
• We welcome contributions or pull requests to improve Nimbus!

---

Citation

If you use Nimbus in your work, please cite:

@article{rum2024nimbus,
  title={Automated classification of cellular expression in multiplexed imaging data with Nimbus},
  author={Rumberger, J. Lorenz and Greenwald, Noah F. and Ranek, Jolene S. and Boonrat, Potchara and Walker, Cameron and Franzen, Jannik and Varra, Sricharan Reddy and Kong, Alex and Sowers, Cameron and Liu, Candace C. and Averbukh, Inna and Piyadasa, Hadeesha and Vanguri, Rami and Nederlof, Iris and Wang, Xuefei Julie and Van Valen, David and Kok, Marleen and Hollman, Travis J. and Kainmueller, Dagmar and Angelo, Michael},
  journal={bioRxiv},
  pages={2024--05},
  year={2024},
  publisher={Cold Spring Harbor Laboratory}
}