splisosm.io

splisosm.io#

I/O loaders for SpatialData-based workflows.

This module provides high-level wrappers for constructing SpatialData objects from platform-specific outputs.

Functions#

load_visium_sp_meta(adata, path_to_spatial[, library_id])

Helper function to load Visium spatial metadata.

load_visiumhd_probe(path[, dataset_id, bin_sizes, ...])

Load Visium HD outputs as SpatialData with probe-level binned tables.

load_xenium_codeword(path[, spatial_resolutions, ...])

Load Xenium outputs and append multi-resolution codeword bin tables.

Module Contents#

splisosm.io.load_visium_sp_meta(adata, path_to_spatial, library_id=None)#

Helper function to load Visium spatial metadata.

Parameters:

  • adata (AnnData) – Annotated data matrix to store the spatial metadata.

  • path_to_spatial (str | pathlib.Path) – Path to the spatial folder generated by Space Ranger.

  • library_id (Optional[str]) – Library ID of the spatial data.

Returns:

anndata – AnnData with spatial metadata.

Return type:

AnnData

splisosm.io.load_visiumhd_probe(path, dataset_id=None, bin_sizes=None, bins_as_squares=True, fullres_image_file=None, load_all_images=False, var_names_make_unique=True, filtered_counts_file=True, counts_layer_name='counts', path_to_feature_2um_h5=None)#

Load Visium HD outputs as SpatialData with probe-level binned tables.

This wrapper uses binned_outputs/square_002um/raw_probe_bc_matrix.h5 (or a custom path_to_feature_2um_h5) as the source feature count matrix. It aggregates probe/peak/isoform counts to coarser bins or cells (square_008um, square_016um and, when available, cell_id) according to the spatial mapping barcode_mappings.parquet (Space Ranger v4.0+ required).

Parameters:

  • path (str | pathlib.Path) – Path to Space Ranger outs directory for Visium HD.

  • dataset_id (Optional[str]) – Optional dataset ID passed to the SpatialData reader.

  • bin_sizes (Optional[list[int | str]]) – Bin resolutions to include. Each entry can be int (for example 8) or Visium HD bin string (for example "square_008um"). If None, all available square_*um bins under binned_outputs are used.

  • bins_as_squares (bool) – Whether bins are represented as squares when loading shapes.

  • fullres_image_file (Optional[str | pathlib.Path]) – Path to the full-resolution image.

  • load_all_images (bool) – Whether to load all optional images via spatialdata_io reader.

  • var_names_make_unique (bool) – Whether to call var_names_make_unique() on probe table variables.

  • filtered_counts_file (bool) – Whether to keep only in-tissue 2um barcodes prior to aggregation. If True, barcodes are taken from the source bin table loaded by visium_hd (square_002um). If unavailable, the function falls back to binned_outputs/square_002um/filtered_feature_bc_matrix.h5.

  • counts_layer_name (str) – Layer name used to store aggregated probe counts in each output table.

  • path_to_feature_2um_h5 (Optional[str | pathlib.Path]) – Optional path to the raw 2um probe/peak/isoform counts matrix H5 or H5AD. If not provided, will look for binned_outputs/square_002um/raw_feature_bc_matrix.h5.

Returns:

A SpatialData object with probe-level tables for requested bins and, if available, cell-level segmentation.

Return type:

SpatialData

Raises:

  • ImportError – If required optional dependencies are not installed.

  • ValueError – If required files or requested bins are missing.

splisosm.io.load_xenium_codeword(path, spatial_resolutions=(8.0, 16.0), quality_threshold=20.0, n_jobs=-1, chunk_batch_size=64, counts_layer_name='counts', build_cell_codeword_table=True, create_square_shapes=True, cells_boundaries=True, nucleus_boundaries=True, cells_as_circles=False, cells_labels=True, nucleus_labels=True, transcripts=True, morphology_mip=True, morphology_focus=True, aligned_images=True, cells_table=True, gex_only=True, show_progress=True)#

Load Xenium outputs and append multi-resolution codeword bin tables.

This wrapper reads Xenium Ranger outs with spatialdata-io and then quantifies codewords into square spatial bins at one or more user-defined resolutions using transcript-level chunk data (grids/0/*). Counting is implemented with vectorized sparse aggregation over (spot, codeword) pairs to reduce Python overhead while avoiding dependence on optional precomputed density matrices. For each resolution, a table named square_XXXum is added to sdata.tables; optional square geometries with a _bins suffix are added to sdata.shapes so the tables can be used directly with spatialdata.rasterize_bins().

transcripts.zarr.zip is expected to contain the density/codeword group for codeword indexing (Xenium Ranger v3.1+ required). If build_cell_codeword_table=True and the transcripts.parquet file is available, a cell-by-codeword anndata named table_codeword will also be built and added to sdata.tables.

Parameters:

  • path (str | pathlib.Path) – Path to Xenium Ranger output directory, or its parent containing outs/.

  • spatial_resolutions (collections.abc.Sequence[float] | None) – Spatial bin sizes in microns. Pass None or an empty sequence to skip bin table creation entirely (cell-segmentation-only mode).

  • quality_threshold (float) – Minimum transcript quality score to retain.

  • n_jobs (int) – Parallel worker count for chunk processing. Use -1 for all cores.

  • chunk_batch_size (int) – Number of transcript chunks submitted per processing batch.

  • counts_layer_name (str) – Layer name used to store codeword counts in each output table.

  • build_cell_codeword_table (bool) – Whether to build a cell-by-codeword table from the transcripts parquet file.

  • create_square_shapes (bool) – Whether to create square bin shapes for each table key.

  • cells_boundaries (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • nucleus_boundaries (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • cells_as_circles (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • cells_labels (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • nucleus_labels (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • transcripts (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • morphology_mip (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • morphology_focus (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • aligned_images (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • cells_table (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • gex_only (bool) – Passed to spatialdata_io.readers.xenium.xenium.

  • show_progress (bool) – Whether to display progress bars while binning codewords.

Returns:

SpatialData object augmented with bin-by-codeword count tables at each requested resolution and, when requested, a cell-by-codeword table named table_codeword.

Return type:

SpatialData

Raises:

  • ImportError – If required optional dependencies are not installed.

  • ValueError – If path/layout/arguments are invalid.