Metadata-Version: 2.5
Name: harpy-analysis
Version: 0.5.0
Summary: single-cell spatial omics analysis that makes you happy.
Project-URL: Homepage, https://github.com/saeyslab/harpy
Project-URL: Documentation, https://harpy.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/saeyslab/harpy
Project-URL: Issues, https://github.com/saeyslab/harpy/issues
Project-URL: Changelog, https://github.com/saeyslab/harpy/releases
Project-URL: Paper, https://doi.org/10.1093/bioinformatics/btag122
Project-URL: SaeysLab, https://saeyslab.sites.vib.be/en
Project-URL: VIBSpatialCatalyst, https://vib.be/en/technologies/technology-portfolio/spatial-catalyst
Author: Saeys Lab, VIB spatial catalyst
License: BSD 3-Clause License
        
        Copyright (c) 2026, VIB vzw
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: anndata,bioinformatics,image-analysis,scanpy,scverse,single-cell,spatial-omics,spatial-proteomics,spatial-transcriptomics,spatialdata
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: <3.15,>=3.12
Requires-Dist: anndata>=0.12.10
Requires-Dist: crick
Requires-Dist: distributed
Requires-Dist: filelock
Requires-Dist: flowsom
Requires-Dist: lazy-loader>=0.4
Requires-Dist: leidenalg>=0.9.1
Requires-Dist: ome-zarr>=0.14.0
Requires-Dist: pyrootutils
Requires-Dist: rasterio>=1.3.2
Requires-Dist: scanpy>=1.11.1
Requires-Dist: scikit-learn>=1.3.1
Requires-Dist: seaborn>=0.12.2
Requires-Dist: session-info2
Requires-Dist: spatialdata-io>=0.7.0
Requires-Dist: spatialdata-plot
Requires-Dist: spatialdata>=0.7.3
Requires-Dist: tifffile>=2026.5.2
Requires-Dist: universal-pathlib
Requires-Dist: voronoi-diagram-for-polygons>=0.1.6
Requires-Dist: zarr>=3.2.1
Provides-Extra: benchmark
Requires-Dist: asv; extra == 'benchmark'
Provides-Extra: cellpose
Requires-Dist: cellpose<5,>=3.1.1.3; extra == 'cellpose'
Provides-Extra: cellpose3
Requires-Dist: cellpose<4,>=3.1.1.3; extra == 'cellpose3'
Provides-Extra: cellpose4
Requires-Dist: cellpose<5,>=4; extra == 'cellpose4'
Provides-Extra: dev
Requires-Dist: asv; extra == 'dev'
Requires-Dist: bokeh; extra == 'dev'
Requires-Dist: cellpose<5,>=3.1.1.3; extra == 'dev'
Requires-Dist: harpy-vitessce; (python_version >= '3.12') and extra == 'dev'
Requires-Dist: instanseg-torch>=0.1.1; extra == 'dev'
Requires-Dist: ipython; extra == 'dev'
Requires-Dist: ipywidgets; extra == 'dev'
Requires-Dist: joypy; extra == 'dev'
Requires-Dist: marimo>=0.24.2; extra == 'dev'
Requires-Dist: myst-nb; extra == 'dev'
Requires-Dist: nbconvert; extra == 'dev'
Requires-Dist: opencv-python-headless; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest-xdist; extra == 'dev'
Requires-Dist: sphinx-autodoc-typehints; extra == 'dev'
Requires-Dist: sphinx-book-theme>=1.0.0; extra == 'dev'
Requires-Dist: sphinx-copybutton; extra == 'dev'
Requires-Dist: sphinx-design; extra == 'dev'
Requires-Dist: sphinx-rtd-theme; extra == 'dev'
Requires-Dist: sphinx>=4.5; extra == 'dev'
Requires-Dist: sphinxcontrib-bibtex>=1.0.0; extra == 'dev'
Requires-Dist: sphinxcontrib-mermaid; extra == 'dev'
Requires-Dist: supervenn>=0.5.0; extra == 'dev'
Requires-Dist: textalloc; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: tqdm; extra == 'dev'
Requires-Dist: twine>=4.0.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-nb; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx-book-theme>=1.0.0; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx-rtd-theme; extra == 'docs'
Requires-Dist: sphinx>=4.5; extra == 'docs'
Requires-Dist: sphinxcontrib-bibtex>=1.0.0; extra == 'docs'
Requires-Dist: sphinxcontrib-mermaid; extra == 'docs'
Provides-Extra: extra
Requires-Dist: bokeh; extra == 'extra'
Requires-Dist: cellpose<5,>=3.1.1.3; extra == 'extra'
Requires-Dist: harpy-vitessce; (python_version >= '3.12') and extra == 'extra'
Requires-Dist: instanseg-torch>=0.1.1; extra == 'extra'
Requires-Dist: ipython; extra == 'extra'
Requires-Dist: ipywidgets; extra == 'extra'
Requires-Dist: joypy; extra == 'extra'
Requires-Dist: marimo>=0.24.2; extra == 'extra'
Requires-Dist: nbconvert; extra == 'extra'
Requires-Dist: opencv-python-headless; extra == 'extra'
Requires-Dist: supervenn>=0.5.0; extra == 'extra'
Requires-Dist: textalloc; extra == 'extra'
Requires-Dist: tqdm; extra == 'extra'
Provides-Extra: instanseg
Requires-Dist: instanseg-torch>=0.1.1; extra == 'instanseg'
Provides-Extra: napari
Requires-Dist: napari[all]>=0.7.1; extra == 'napari'
Requires-Dist: spatiato>=0.2.0; extra == 'napari'
Provides-Extra: notebook
Requires-Dist: bokeh; extra == 'notebook'
Requires-Dist: ipython; extra == 'notebook'
Requires-Dist: ipywidgets; extra == 'notebook'
Requires-Dist: joypy; extra == 'notebook'
Requires-Dist: marimo>=0.24.2; extra == 'notebook'
Requires-Dist: nbconvert; extra == 'notebook'
Requires-Dist: supervenn>=0.5.0; extra == 'notebook'
Requires-Dist: textalloc; extra == 'notebook'
Requires-Dist: tqdm; extra == 'notebook'
Provides-Extra: opencv
Requires-Dist: opencv-python-headless; extra == 'opencv'
Provides-Extra: test
Requires-Dist: opencv-python-headless; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pytest-xdist; extra == 'test'
Requires-Dist: tox; extra == 'test'
Provides-Extra: vitessce
Requires-Dist: harpy-vitessce; (python_version >= '3.12') and extra == 'vitessce'
Description-Content-Type: text/markdown

<!-- These badges won't work while the GitHub repo is private:
[![License BSD-3](https://img.shields.io/pypi/l/harpy-analysis.svg?color=green)](https://github.com/saeyslab/harpy/raw/main/LICENSE)
[![Python Version](https://img.shields.io/pypi/pyversions/harpy-analysis.svg?color=green)](https://python.org)
[![codecov](https://codecov.io/gh/saeyslab/harpy/graph/badge.svg?token=7UXMDWVYFZ)](https://codecov.io/gh/saeyslab/harpy)
-->

<div align="center">
  <img src="https://raw.githubusercontent.com/saeyslab/harpy/main/docs/_static/img/logo.png" alt="Harpy logo" width="200" />
  <h2>Single-cell spatial omics analysis that makes you happy.</h2>
</div>

<div align="center">

[![PyPI](https://img.shields.io/pypi/v/harpy-analysis.svg)](https://pypi.org/project/harpy-analysis)
[![Release Status](https://github.com/saeyslab/harpy/actions/workflows/release.yaml/badge.svg)](https://github.com/saeyslab/harpy/actions/workflows/release.yaml)
[![Build Status](https://github.com/saeyslab/harpy/actions/workflows/build.yaml/badge.svg)](https://github.com/saeyslab/harpy/actions/)
[![Test Status](https://github.com/saeyslab/harpy/actions/workflows/run_tests.yml/badge.svg)](https://github.com/saeyslab/harpy/actions/)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/saeyslab/harpy/main.svg)](https://results.pre-commit.ci/latest/github/saeyslab/harpy/main)
[![documentation badge](https://readthedocs.org/projects/harpy/badge/?version=latest)](https://harpy.readthedocs.io/en/latest/)
[![codecov](https://codecov.io/gh/saeyslab/harpy/branch/main/graph/badge.svg)](https://codecov.io/gh/saeyslab/harpy)
[![Downloads](https://static.pepy.tech/badge/harpy-analysis)](https://pepy.tech/project/harpy-analysis)
[![License](https://img.shields.io/badge/license-BSD%203--Clause-blue)](./LICENSE)
![GitHub repo size](https://img.shields.io/github/repo-size/saeyslab/harpy)
[![Zenodo](https://zenodo.org/badge/763481288.svg)](https://zenodo.org/badge/latestdoi/763481288)
[![Paper](https://img.shields.io/badge/Paper-Bioinformatics%20btag122-blue)](https://doi.org/10.1093/bioinformatics/btag122)

</div>

<p align="center">
  <a href="https://harpy.readthedocs.io/en/latest/">Documentation</a>
  ·
  <a href="https://harpy.readthedocs.io/en/latest/quickstart.html">Quick Start</a>
  ·
  <a href="https://harpy.readthedocs.io/en/latest/tutorials/index.html">Tutorials</a>
  ·
  <a href="https://github.com/vibspatial/napari-harpy">napari-harpy</a>
  ·
  <a href="https://github.com/vibspatial/harpy_vitessce">harpy-vitessce</a>
</p>

> 💫 **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?

Harpy is a spatial omics analysis library for spatial transcriptomics and proteomics. Within the [`scverse`](https://scverse.org/) stack, it bridges [`SpatialData`](https://spatialdata.scverse.org/) and downstream analysis tools such as [`AnnData`](https://anndata.readthedocs.io/), [`Scanpy`](https://scanpy.readthedocs.io/), and [`Squidpy`](https://squidpy.readthedocs.io/). It provides scalable, image- and geometry-aware computation to transform raw spatial data into analysis-ready representations, with a strong emphasis on interoperability and large-scale workflows.

In practice, Harpy offers fast, out-of-core image preprocessing, tiled segmentation, along with efficient aggregation workflows to generate `AnnData` tables and compute per-cell features from images, segmentation masks, and transcript coordinates. It also supports deep feature extraction, pixel- and cell-level clustering, and the construction of single-cell representations from highly multiplexed images.

- **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/).
- **Scalable computational building blocks** for segmentation, feature extraction, clustering, and spatial analysis.

## Installation

```bash
pip install harpy-analysis
```

**With extras**

```bash
pip install "harpy-analysis[extra]"
```

`[extra]` installs optional dependencies for:

- Segmentation: `cellpose`, `instanseg-torch`
- OpenCV support: `opencv-python-headless`
- FlowSOM Clustering: `flowsom`
- Vitessce: `harpy-vitessce`
- Notebook workflows: `ipywidgets`, `tqdm`, `bokeh`, `textalloc`, `joypy`, `supervenn`, `nbconvert`, `ipython`

**With extras and napari**

```bash
pip install "harpy-analysis[extra,napari]"
```

`[napari]` adds:

- `napari[all]`
- `napari-harpy`
- `napari-spatialdata`

**Only for developers.** Clone this repository locally, install the `.[dev]` instead of the `[extra]` dependencies and read the [contribution guide](https://harpy.readthedocs.io/en/latest/contributing.html).

```bash
# Clone repository from GitHub
uv venv --python=3.12  # create venv, set python version (>=3.11)
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
```

For more installation details, see the [installation guide](./docs/installation.md).

## Quickstart

See the short, runnable [guide](https://harpy.readthedocs.io/en/latest/quickstart.html).

## API Changes in 0.4.0

> Note for users upgrading to Harpy `0.4.0`: parameters that refer to `SpatialData` elements now use the `*_name` convention instead of the older `*_layer` naming to stay aligned with scverse naming conventions. For example, `img_layer` becomes `image_name`, `labels_layer` becomes `labels_name`, and `table_layer` becomes `table_name`.

The examples in this README and in the documentation already follow the `0.4.0` naming convention.

## 🧭 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, perform QC and analyze results downstream with `Scanpy` and `Squidpy`.

  👉 [Tutorial image based transcriptomics, Human Ovarian Cancer, Xenium 10x Genomics](https://harpy.readthedocs.io/en/latest/tutorials/general/Harpy_xenium_transcriptomics_subset.html)

  👉 [Tutorial proteomics, MACSima](https://harpy.readthedocs.io/en/latest/tutorials/general/Harpy_feature_calculation.html)

- **🔧 Technology-specific advice**

  Learn which technologies Harpy supports. 👉 [Tutorial](https://harpy.readthedocs.io/en/latest/tutorials/general/techno_specific.html)

- **🧩 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](https://harpy.readthedocs.io/en/latest/tutorials/general/FlowSOM_for_pixel_and_cell_clustering.html)

- **✂️ Cell Segmentation**

  Explore segmentation workflows in `Harpy` using different tools:
  - With [**Instanseg**](https://github.com/instanseg/instanseg) 👉 [Tutorial](https://harpy.readthedocs.io/en/latest/tutorials/general/Harpy_instanseg.html)

  - With [**Cellpose**](https://github.com/MouseLand/cellpose) 👉 [Tutorial](https://harpy.readthedocs.io/en/latest/tutorials/general/Harpy_feature_calculation.html)

  💡 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](https://harpy.readthedocs.io/en/latest/tutorials/general/generate_single_cell_representations.html)

- **🧠 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](https://harpy.readthedocs.io/en/latest/tutorials/general/Featurize_with_kronos.html)

  💡 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](https://harpy.readthedocs.io/en/latest/tutorials/advanced/Harpy_aggregate_rasters.html)

- **🧬 Spatial Transcriptomics**

  Learn how to analyze spatial transcriptomics data with `Harpy`.

  👉 [Tutorial (Mouse Liver, Resolve Molecular Cartography)](https://harpy.readthedocs.io/en/latest/tutorials/advanced/Harpy_transcriptomics.html)

  👉 [Tutorial (Human Ovarian Cancer, Xenium 10x Genomics)](https://harpy.readthedocs.io/en/latest/tutorials/advanced/Harpy_transcriptomics_xenium.html)

---

- **🌐 Multiple samples and coordinate systems**

  Learn how to work with multiple samples, intrinsic and micron coordinates. 👉 [Tutorial](https://harpy.readthedocs.io/en/latest/tutorials/advanced/coordinate_systems.html)

---

- **📐 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](https://harpy.readthedocs.io/en/latest/tutorials/advanced/Rasterize_and_vectorize.html)

---

📚 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](https://harpy.readthedocs.io/en/latest/tutorials/general/benchmark.html)

## Contributing

See the [contribution guide](https://harpy.readthedocs.io/en/latest/contributing.html) for info on how to contribute to Harpy.

## Citation

If you use Harpy in your work, please cite:

> Benjamin Rombaut, Arne Defauw, Frank Vernaillen, Julien Mortier, Evelien Van Hamme, Sofie Van Gassen, Ruth Seurinck, Yvan Saeys. _Scalable analysis of whole slide spatial proteomics with Harpy_. _Bioinformatics_ (2026), btag122. [https://doi.org/10.1093/bioinformatics/btag122](https://doi.org/10.1093/bioinformatics/btag122)

If you use Harpy for spatial transcriptomics analysis, please cite:

> Lotte Pollaris, Bavo Vanneste, Benjamin Rombaut, Arne Defauw, Frank Vernaillen, Julien Mortier, Wout Vanhenden, Liesbet Martens, Tinne Thone, Jean-Francois Hastir, Anna Bujko, Wouter Saelens, Jean-Christophe Marine, Hilde Nelissen, Evelien Van Hamme, Ruth Seurinck, Charlotte L. Scott, Martin Guilliams, Yvan Saeys. _SPArrOW: a flexible, interactive and scalable pipeline for spatial transcriptomics analysis_. [https://doi.org/10.1101/2024.07.04.601829](https://doi.org/10.1101/2024.07.04.601829)

## License

Harpy is licensed under the [BSD 3-Clause License](./LICENSE).

## 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
[file an issue]: https://github.com/saeyslab/harpy/issues
[tox]: https://tox.readthedocs.io/en/latest/
[pip]: https://pypi.org/project/pip/
[PyPI]: https://pypi.org/
