harpy.io.xenium

Contents

harpy.io.xenium#

harpy.io.xenium(path, to_coordinate_system='global', aligned_images=True, cells_labels=True, nucleus_labels=True, morphology_mip=False, morpholohy_focus=True, cells_table=True, filter_gene_names=None, imread_kwargs=mappingproxy({}), image_models_kwargs=mappingproxy({}), labels_models_kwargs=mappingproxy({}), instance_key='cell_ID', region_key='fov_labels', spatial_key='spatial', output=None)#

Read a 10X Genomics Xenium dataset into a SpatialData object.

Wrapper around spatialdata_io.xenium() that adds some additional capabilities: (i) adding a micron-based coordinate system, and (ii) loading multiple samples into a single SpatialData object.

This function reads images, transcripts, masks (cell and nuclei) and tables, so it can be used for analysis. The resulting AnnData table will be annotated by a labels element.

The micron coordinate system is added as ‘{to_coordinate_system}_micron’ and is available to all spatial elements within the resulting SpatialData object.

Cell and nuclear boundaries provided by Xenium will not be loaded, as these polygonal versions of the cell and nucleus labels are approximations. They can however be generated from the cell and nuclear labels using harpy.sh.vectorize().

This function reads the following files:

  • {xx.XENIUM_SPECS!r}: File containing specifications.

  • {xx.TRANSCRIPTS_FILE!r}: File containing transcripts.

  • {xx.CELL_FEATURE_MATRIX_FILE!r}: File containing cell feature matrix.

  • {xx.CELL_METADATA_FILE!r}: File containing cell metadata.

  • {xx.MORPHOLOGY_MIP_FILE!r}: File containing morphology mip.

  • {xx.MORPHOLOGY_FOCUS_FILE!r}: File containing morphology focus.

See also

Parameters:

  • path (str | Path | list[str] | list[Path]) – Specifies the location of the dataset. This can either be a single path or a list of paths, where each path corresponds to a different experiment/roi.

  • to_coordinate_system (str | list[str] (default: 'global')) – The coordinate system to which the images, segmentation masks and transcripts will be added for each item in path. If provided as a list, its length should be equal to the number of paths specified in path.

  • aligned_images (bool (default: True)) – Whether to also parse, when available, additional H&E or IF aligned images. For more control over the aligned images being read, in particular, to specify the axes of the aligned images, please set this parameter to False and use the xenium_aligned_image function directly.

  • cells_labels (bool (default: True)) – Whether to read cell labels (raster) provided by Xenium. The polygonal version of the cell labels are simplified for visualization purposes, and using the raster version is recommended for analysis.

  • nucleus_labels (bool (default: True)) – Whether to read nucleus labels (raster) provided by Xenium. The polygonal version of the nucleus labels are simplified for visualization purposes, and using the raster version is recommended for analysis.

  • morphology_mip (bool (default: False)) – Whether to read the morphology mip image (available in versions < 2.0.0).

  • morphology_focus – Whether to read the morphology focus image.

  • cells_table (bool (default: True)) – Whether to read the cell annotations in the AnnData table. Will be added to the f"table_{to_coordinate_system}" slot in sdata.tables, or f”table_{to_coordinate_system[i]}” if to_coordinate_system is a list. If True, labels element annotating the table will also be added to sdata.

  • filter_gene_names (str | list[str] (default: None)) – Gene names that need to be filtered out (via str.contains), mostly control genes that were added, and which you don’t want to use. Filtering is case insensitive. Also see harpy.read_transcripts().

  • imread_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments to pass to the image reader.

  • image_models_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments to pass to the image models.

  • labels_models_kwargs (Mapping[str, Any] (default: mappingproxy({}))) – Keyword arguments to pass to the labels models.

  • instance_key (str (default: 'cell_ID')) – Instance key. The name of the column in AnnData table .obs that will hold the instance ids. Ignored if table is False.

  • region_key (str (default: 'fov_labels')) – Region key. The name of the column in AnnData table .obs that will hold the name of the elements that annotate the table. Ignored if table is False.

  • spatial_key (str (default: 'spatial')) – The key in the AnnData table .obsm that will hold the x and y center of the instances. Ignored if table is False.

  • output (str | Path | None (default: None)) – The path where the resulting SpatialData object object will be backed. If None, it will not be backed to a Zarr store.

Raises:

  • AssertionError – Raised when the number of elements in path and to_coordinate_system are not the same.

  • AssertionError – If elements in to_coordinate_system are not unique.

  • AssertionError – If cells_table is True, but the labels element annotating the table is not found.

Return type:

SpatialData

Returns:

: A SpatialData object object.

Contents