insitupy.io.read_qupath

Contents

insitupy.io.read_qupath#

insitupy.io.read_qupath(path, pixel_size, dataset_name, sample_name, method_name='mIF')#

Load and process QuPath-exported spatial data into an InSituData object.

This function reads annotation, cellular measurements, cell boundaries, and image data from a specified directory containing QuPath outputs. It applies coordinate shifts to align image data and transcriptomic data relative to the origin. All components are integrated into a structured InSituData object for downstream spatial analysis.

Parameters:

  • path (Union[str, PathLike, Path]) – Path to the directory containing QuPath-exported files.

  • pixel_size (Number) – Pixel size used to scale coordinates from annotation geometry.

  • dataset_name (str) – Identifier for the dataset or slide.

  • sample_name (str) – Identifier for the sample within the dataset.

  • method_name (str (default: 'mIF')) – Name of the imaging method used. Defaults to multiplexed IF (“mIF”).

Returns:

A structured object containing image data, cell measurements, and boundaries.

Return type:

InSituData

Raises:

  • FileNotFoundError – If any of the required files (annotation.geojson, measurements.tsv, cells.geojson, or image.ome.tif) are missing in the specified path.

  • ValueError – If more than one annotation geometry is found in the annotation file.

Notes

The expected directory structure should include the following files:

  • annotation.geojson: A single annotation encircling the dataset. Contains information about the shift of the data relative to the origin.

  • measurements.tsv: Tabular data with cellular measurements. Measurements are divided into ‘Cell’, ‘Nucleus’, ‘Cytoplasm’, and ‘Membrane’. These are saved as layers in the final AnnData object in data.cells.table.

  • cells.geojson: Nuclear and cellular boundaries of individual cells.

  • image.ome.tif: The corresponding image file.

To generate data in the correct format from QuPath, use the following export script: SpatialPathology/InSituPy-QuPath

Example

>>> data = read_qupath(
...     path="/data/qupath_export",
...     pixel_size=0.65,
...     dataset_name="Slide001",
...     sample_name="SampleA"
... )
Contents