https://github.com/saeyslab/harpy
Single-cell spatial omics analysis that makes you happy!
https://github.com/saeyslab/harpy
analysis-framework bioinformatics hpc machine-learning microscopy napari-plugin spatial
Last synced: about 8 hours ago
JSON representation
Single-cell spatial omics analysis that makes you happy!
- Host: GitHub
- URL: https://github.com/saeyslab/harpy
- Owner: saeyslab
- License: other
- Created: 2024-02-26T11:30:00.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-24T19:11:32.000Z (20 days ago)
- Last Synced: 2026-02-24T23:43:33.891Z (19 days ago)
- Topics: analysis-framework, bioinformatics, hpc, machine-learning, microscopy, napari-plugin, spatial
- Language: Python
- Homepage: https://harpy.readthedocs.io/en/latest/
- Size: 812 MB
- Stars: 52
- Watchers: 4
- Forks: 6
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: docs/contributing.md
- License: LICENSE
Awesome Lists containing this project
README
Single-cell spatial omics analysis that makes you happy.
[](https://pypi.org/project/harpy-analysis)
[](https://pepy.tech/project/harpy-analysis)
[](https://github.com/saeyslab/harpy/actions/)
[](https://harpy.readthedocs.io/en/latest/)
[](https://github.com/saeyslab/harpy/actions/)
[](https://codecov.io/gh/saeyslab/harpy)
[](./LICENSE)
[](https://github.com/astral-sh/uv)
[](https://github.com/astral-sh/ruff)
Documentation
·
Quick Start
·
Tutorials
·
Harpy Vitessce
> 💫 **If you find Harpy useful, please give us a [⭐](https://github.com/saeyslab/harpy)!** It helps others discover the project and supports continued development.
## Why Harpy?
- **Multi-platform support** for spatial transcriptomics and proteomics data.
- **Interoperable outputs** built on [SpatialData](https://github.com/scverse/spatialdata).
- **Scales to (very) large images**: tiled workflows with [Dask](https://www.dask.org/); optional GPU acceleration with [CuPy](https://cupy.dev/) and [PyTorch](https://pytorch.org/).
- **End-to-end workflows** for segmentation, feature extraction, clustering, and spatial analysis.
## Installation
**Recommended** for end-users (Python `>=3.11`).
```bash
uv venv --python=3.12 # set python version
source .venv/bin/activate # activate the virtual environment
uv pip install "harpy-analysis[extra]" # use uv to pip install dependencies
python -c 'import harpy; print(harpy.__version__)' # check if the package is installed
```
**Only for developers.** Clone this repository locally, install the `.[dev]` instead of the `[extra]` dependencies and read the contribution guide.
```bash
# Clone repository from GitHub
uv venv --python=3.12 # set python version
source .venv/bin/activate # activate the virtual environment
uv pip install -e '.[dev]' # editable install with dev tooling
python -c 'import harpy; print(harpy.__version__)' # check if the package is installed
# make changes
python -m pytest # run the tests
```
Checkout the docs for [installation instructions](https://github.com/saeyslab/harpy/blob/main/docs/installation.md) using [conda](https://github.com/conda/conda).
## Quickstart
See the short, runnable [guide](./docs/quickstart.md).
## 🧭 Tutorials and Guides
Explore how to use Harpy for segmentation, shallow and deep feature extraction, clustering, and spatial analysis of gigapixel-scale multiplexed data with these step-by-step notebooks:
- **🚀 Basic Usage of Harpy**
Learn how to read in data, perform **tiled segmentation** using [**Cellpose**](https://github.com/MouseLand/cellpose) and [**Dask-CUDA**](https://docs.rapids.ai/api/dask-cuda/stable/), extract features, and carry out clustering. 👉 [Tutorial](./docs/tutorials/general/Harpy_feature_calculation.ipynb)
- **🔧 Technology-specific advice**
Learn which technologies Harpy supports. 👉 [Notebook](./docs/tutorials/general/techno_specific.ipynb)
- **🧩 Pixel and Cell Clustering**
Learn how to perform unsupervised pixel- and cell-level clustering using `Harpy` together with [**FlowSOM**](https://github.com/saeyslab/FlowSOM_Python). 👉 [Tutorial](./docs/tutorials/general/FlowSOM_for_pixel_and_cell_clustering.ipynb)
- **✂️ Cell Segmentation**
Explore segmentation workflows in `Harpy` using different tools:
- With [**Instanseg**](https://github.com/instanseg/instanseg) 👉 [Tutorial](./docs/tutorials/general/Harpy_instanseg.ipynb)
- With [**Cellpose**](https://github.com/MouseLand/cellpose) 👉 [Tutorial](./docs/tutorials/general/Harpy_feature_calculation.ipynb)
💡 Want us to add support for another segmentation method?
👉 [Open an issue](https://github.com/saeyslab/harpy/issues) and let us know!
- **🧪 Single-cell representations from highly multiplexed images and downstream use with [PyTorch](https://pytorch.org/)**
Learn how single-cell representations can be generated from highly multiplexed images. These representations can then be used downstream to train classifiers in PyTorch. 👉 [Tutorial](./docs/tutorials/general/generate_single_cell_representations.ipynb)
- **🧠 Deep Feature Extraction**
Discover how `Harpy` enables fast, scalable extraction of deep, cell-level features from multiplex imaging data with the [**KRONOS**](https://github.com/mahmoodlab/KRONOS) foundation model for proteomics. 👉 [Tutorial](./docs/tutorials/general/Featurize_with_kronos.ipynb)
💡 Want us to add support for another deep feature extraction method?
👉 [Open an issue](https://github.com/saeyslab/harpy/issues) and let us know!
- **🔬 Shallow Feature Extraction**
Learn to extract shallow features—such as **mean**, **median**, and **standard deviation** of intensities—from multiplex imaging data with `Harpy`. 👉 [Tutorial](./docs/tutorials/advanced/Harpy_aggregate_rasters.ipynb)
- **🧬 Spatial Transcriptomics**
Learn how to analyze spatial transcriptomics data with `Harpy`. For detailed information, refer to the [**SPArrOW documentation**](https://sparrow-pipeline.readthedocs.io/en/latest).
👉 [Tutorial (Mouse Liver, Resolve Molecular Cartography)](./docs/tutorials/advanced/Harpy_transcriptomics.ipynb)
👉 [Tutorial (Human Ovarian Cancer, Xenium 10x Genomics)](./docs/tutorials/advanced/Harpy_transcriptomics_xenium.ipynb)
---
- **🌐 Multiple samples and coordinate systems**
Learn how to work with multiple samples, intrinsic and micron coordinates. 👉 [Tutorial](./docs/tutorials/advanced/coordinate_systems.ipynb)
---
- **📐 Rasterize and vectorize labels and shapes**
Learn how to convert a segmentation mask (array) into its vectorized form, and segmentation boundaries (polygons) into their rasterized equivalents. This conversion is useful, for example, when integrating annotations (e.g., from [QuPath](https://qupath.github.io/)) into downstream spatial omics analysis.👉 [Tutorial](./docs/tutorials/advanced/Rasterize_and_vectorize.ipynb)
---
📚 For a complete list of tutorials, visit the [**Harpy documentation**](https://harpy.readthedocs.io/en/latest/tutorials).
## Computational benchmark
Explore the benchmark performance of **Harpy** on a large MACSima tonsil proteomics dataset. 👉 [Results](./docs/tutorials/general/benchmark.ipynb)
## Usage
[Learn](https://github.com/saeyslab/harpy/blob/main/docs/usage.md) how `Harpy` can be integrated into your workflow.
## Contributing
See [here](https://github.com/saeyslab/harpy/blob/main/docs/contributing.md) for info on how to contribute to Harpy.
## References
- https://github.com/ashleve/lightning-hydra-template
## License
Check the [license](https://github.com/saeyslab/harpy/blob/main/LICENSE). Harpy is free for academic usage.
For commercial usage, please contact Saeyslab.
## Issues
If you encounter any problems, please [file an issue] along with a detailed description.
[Cookiecutter]: https://github.com/audreyr/cookiecutter
[BSD-3]: http://opensource.org/licenses/BSD-3-Clause
[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin
[file an issue]: https://github.com/saeyslab/harpy/issues
[napari]: https://github.com/napari/napari
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/