spatialrefinery.xenium_to_spatialdata

spatialrefinery.xenium_to_spatialdata#

spatialrefinery.xenium_to_spatialdata(dataset_path, output_path, output_name=None, include_aligned_image=True, create_spots=True, spot_sizes=None, overlap=0.0, values='transcripts', n_jobs=1, overwrite=False, max_spots_per_chunk=50000)#

Convert 10x Xenium raw data to SpatialData zarr format.

This is the main function for converting Xenium bundled outputs to a SpatialData object and saving it as a zarr file. It can optionally include aligned H&E images and create pseudo-spots at specified sizes.

Parameters:

  • dataset_path (str | Path) – Path to the Xenium dataset directory containing raw files.

  • output_path (str | Path) – Path to the directory where the zarr file will be saved.

  • output_name (str | None (default: None)) – Name for the output zarr file (without .zarr extension). If None, uses the dataset directory name. Default is None.

  • include_aligned_image (bool (default: True)) – Whether to include aligned H&E image if available. Default is True.

  • create_spots (bool (default: True)) – Whether to create pseudo-spots. Default is True.

  • spot_sizes (list | None (default: None)) – List of spot sizes in micrometers to create. Default is None. Spots are only created when both create_spots is True and spot_sizes is a non-empty list – the default combination (create_spots=True, spot_sizes=None) creates no spots.

  • overlap (float | None (default: 0.0)) – Fractional overlap between adjacent hexagonal spots, forwarded to create_pseudo_spots. Default is 0.0 (no overlap).

  • values (str (default: 'transcripts')) – Which SpatialData element to aggregate into spots: "transcripts" or "cell_boundaries". Default is "transcripts".

  • n_jobs (int (default: 1)) – Number of workers for parallel processing. Default is 1.

  • overwrite (bool (default: False)) – Whether to overwrite existing zarr file. Default is False.

  • max_spots_per_chunk (int | None (default: 50000)) – Retained for backwards compatibility and ignored; transcript aggregation is now streamed. See create_pseudo_spots.

Return type:

Path

Returns:

Path Path to the created zarr file.

Raises:

FileNotFoundError – If dataset_path does not contain an experiment.xenium file.

Examples

>>> from spatialrefinery import xenium_to_spatialdata
>>> zarr_path = xenium_to_spatialdata(
...     dataset_path="/path/to/xenium/data",
...     output_path="/path/to/output",
...     output_name="my_sample",
...     create_spots=True,
...     spot_sizes=[55, 100],
... )