Metadata-Version: 2.4
Name: Nimbus-Inference
Version: 0.0.5
Summary: A model for classification of cells into marker positive / negative
Project-URL: Documentation, https://Nimbus-Inference.readthedocs.io/
Project-URL: Source, https://github.com/angelolab/Nimbus-Inference
Project-URL: Home-page, https://github.com/angelolab/Nimbus-Inference
Author: Lorenz Rumberger, Noah F. Greenwald
Maintainer-email: Lorenz Rumberger <jlrumber@stanford.edu>, "Noah F. Greenwald" <nfgreen@stanford.edu>, Sricharan Reddy Varra <srivarra@stanford.edu>
License: MIT License
        
        Copyright (c) 2024, Lorenz Rumberger
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.9
Requires-Dist: alpineer
Requires-Dist: datasets<4.0
Requires-Dist: huggingface-hub
Requires-Dist: ipython
Requires-Dist: ipywidgets
Requires-Dist: joblib
Requires-Dist: kornia
Requires-Dist: lmdb
Requires-Dist: mpl-interactions
Requires-Dist: natsort
Requires-Dist: numpy<2.0.0
Requires-Dist: opencv-python-headless
Requires-Dist: pandas
Requires-Dist: pathlib
Requires-Dist: pyometiff
Requires-Dist: scikit-image
Requires-Dist: session-info
Requires-Dist: torch>=2.2.0
Requires-Dist: tqdm
Requires-Dist: zarr
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: twine>=4.0.2; extra == 'dev'
Provides-Extra: doc
Requires-Dist: docutils!=0.18.*,!=0.19.*,>=0.8; extra == 'doc'
Requires-Dist: ipykernel; extra == 'doc'
Requires-Dist: ipython; extra == 'doc'
Requires-Dist: pandas; extra == 'doc'
Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
Requires-Dist: sphinx-copybutton; extra == 'doc'
Requires-Dist: sphinx-rtd-theme>1; extra == 'doc'
Requires-Dist: sphinx>=5; extra == 'doc'
Requires-Dist: sphinxext-opengraph; extra == 'doc'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: coveralls[toml]; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-socket; extra == 'test'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/angelolab/Nimbus-Inference/refs/heads/main/assets/nimbus_logo.png" alt="Nimbus Logo"/>
</p>

![CI](https://github.com/angelolab/Nimbus-Inference/actions/workflows/ci.yaml/badge.svg)
[![Documentation Status](https://readthedocs.org/projects/nimbus-inference/badge/?version=latest)](https://nimbus-inference.readthedocs.io/en/latest/?badge=latest)
[![PyPI Downloads](https://static.pepy.tech/badge/nimbus-inference)](https://pepy.tech/projects/nimbus-inference)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1mLt2K9_rqUhr3Z4CLw_znS12KSUVSPzj?usp=sharing)
[![Nature Methods](https://img.shields.io/badge/Nature%20Methods-Read_Paper-red?style=flat&logo=doi&logoColor=white)](https://www.nature.com/articles/s41592-025-02826-9)

# 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](https://github.com/angelolab/Nimbus) repository 

> **Installation (via pip)**  
> ```bash
> 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](https://github.com/angelolab/Nimbus-Inference/blob/main/templates/1_Nimbus_Predict.ipynb)**  
   - Guides you through performing inference with the Nimbus model on multiplexed imaging data.  
   - [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://drive.google.com/file/d/1k-KnuALBRXbjbkpIP63tf7aEEALw9L1O/view?usp=sharing)  
     
- **[2_Nimbus_Finetuning.ipynb](https://github.com/angelolab/Nimbus-Inference/blob/main/templates/2_Nimbus_Finetuning.ipynb)**  
   - Shows you how to finetune the Nimbus model on a new dataset.  
   - [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://drive.google.com/file/d/1rYYVJQ0nkpG2QE9UjIrzl2x266agdppN/view?usp=sharing)  

- **[3_interactive_viewer.ipynb](https://github.com/angelolab/Nimbus-Inference/blob/main/templates/3_interactive_viewer.ipynb)**  
   - Lets you interactively explore the Nimbus Gold Standard labeled dataset.  
   - [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://drive.google.com/file/d/1LW0vHC3sKKA3TyvW_9FeIaHj3PonzhGS/view?usp=sharing)

- **[4_Generic_Cell_Clustering.ipynb](https://github.com/angelolab/Nimbus-Inference/blob/main/templates/4_Generic_Cell_Clustering.ipynb)**  
   - Performs cell phenotyping using SOM (Self-Organizing Map) and consensus clustering on Nimbus predictions. Takes the cell table output from `1_Nimbus_Predict.ipynb` and clusters cells based on marker expression, enabling downstream analysis and visualization of cell populations.

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](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](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 [publication](https://www.nature.com/articles/s41592-025-02826-9).

---

## 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](https://nimbus-inference.readthedocs.io/en/latest/?badge=latest)

---

## 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:

```bibtex
@article{rumberger2025automated,
  title={Automated classification of cellular expression in multiplexed imaging data with Nimbus},
  author={Rumberger, Josef 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 others},
  journal={Nature Methods},
  volume={22},
  pages={2161–-2170},
  year={2025},
  publisher={Nature Publishing Group US New York}
}
