histolytics 0.3.0

Introduction

histolytics is a spatial analysis library for histological whole slide images (WSI). Built upon torch, geopandas and libpysal, the library provides a comprehensive and scalable framework for panoptic segmentation and interpretable panoptic spatial analysis of routine histopathology slides.

Panoptic Segmentation Features

• Fast WSI-level panoptic segmentation. See example.
• Low memory-footprint segmentation results with __geo_interface__-specification.
• Multiple vectorized segmentation output formats (geojson/feather/parquet).
• Several panoptic segmentation model architectures for histological WSIs with flexible backbone support: See example
• Pre-trained models in model-hub. See: histolytics-hub

Spatial Analysis Features

• Fast Spatial Querying of WSI-scale panoptic segmentation maps. See example
• Spatial indexing/partitioning for localized spatial statistics and analysis. See example
• Graph-based neighborhood analysis for local cell neighborhoods. See example
• Plotting utilities for spatial data visualization. See example
• Spatial clustering and cluster centrography metrics. See example
• Large set of morphological, intensity, chromatin distribution, and textural features at nuclear level. See example
• Large set of collagen fiber and intensity based features to characterize stroma and ECM. See example

Example Workflows

• Immuno-oncology Profiling:
  • Spatial Statistics of TILs.
  • Profiling TLS and Lymphoid Aggregates.
• Nuclear Pleomorphism:
  • Nuclear Morphology Analysis.
  • Nuclear Chromatin Distribution Analysis.
• TME Characterization:
  • Collagen Fiber Disorder Analysis.
  • Characterization of Desmoplastic Stroma.
• Nuclei Neighborhoods:
  • Tumor Cell Accessibility.

Installation

pip install 'histolytics[all]'               # Recommended full installation (Linux)
pip install histolytics                      # CPU spatial/image analysis
pip install 'histolytics[segmentation]'       # Models and segmentation workflows
pip install 'histolytics[cucim]'              # Retained cuCIM WSI backend (Linux)
pip install 'histolytics[cuda-analysis]'      # Existing CUDA analysis (Linux)

These groups apply to Histolytics 0.3.0 and later. Histolytics 0.2.5 retains its previous installation requirements. Existing model users must select segmentation or all; to retain all prior capabilities on Linux, install histolytics[all]. See the installation guide for source installation, reader prerequisites, and CPU Torch setup.

Models

• Panoptic HoVer-Net
• Panoptic Cellpose
• Panoptic Stardist
• Panoptic CellVit-SAM
• Panoptic CPP-Net

Contributing

We welcome contributions! To get started:

1. Fork the repository and create your branch from main.
2. Make your changes with clear commit messages.
3. Ensure all tests pass and add new tests as needed.
4. Submit a pull request describing your changes.

See contributing guide for detailed guidelines.

Citation

If you use histolytics in your research, please cite:

Lehtonen, O., Nordlund, N., Salloum, S., Kalliala, I., Virtanen, A., & Hautaniemi, S. (2025). Histolytics: A panoptic spatial analysis framework for interpretable histopathology. Computational and Structural Biotechnology Journal, 27, 5135–5147. https://doi.org/10.1016/j.csbj.2025.11.022

@article{2025histolytics,
  title={{Histolytics}: A panoptic spatial analysis framework for interpretable histopathology},
  author={Lehtonen, Oskari and Nordlund, Niko and Salloum, Shams and Kalliala, Ilkka and Virtanen, Anni and Hautaniemi, Sampsa},
  journal={Computational and Structural Biotechnology Journal},
  volume={27},
  pages={5135--5147},
  year={2025},
  doi={10.1016/j.csbj.2025.11.022},
  url={https://doi.org/10.1016/j.csbj.2025.11.022},
  publisher={Elsevier}
}