toSpatialData

toSpatialData

toSpatialData(
    data,
    imageId="imageid",
    xCoordinate="X_centroid",
    yCoordinate="Y_centroid",
    radius=None,
    area="Area",
    instanceKey="CellID",
    regionKey=None,
    tableName="table",
    outputDir=None,
    verbose=True,
    sdataTable=None,
)

Convert a cell table into a scverse SpatialData.

One circles element is created per image, holding that image's cell centroids, and the whole table is attached to those elements as a SpatialData table. Every obs column is preserved, so a z-coordinate or any other metadata survives the conversion even though the geometry itself is two-dimensional.

A SpatialData passed in is returned unchanged, which makes the call safe to leave at the top of a pipeline that might receive either kind of input.

Parameters:

Name	Type	Description	Default
data	(AnnData | SpatialData | str, required)	The cell table. An AnnData, a path to an .h5ad file, a SpatialData object, or a path to a .zarr SpatialData store. A SpatialData is returned unchanged.	required
imageId	str	Column in obs identifying the image each cell belongs to. One element is built per distinct value.	'imageid'
xCoordinate	str	Column in obs holding x positions.	'X_centroid'
yCoordinate	str	Column in obs holding y positions.	'Y_centroid'
radius	str | float	Circle radius: an obs column name, a plain number, or None to derive it from area.	None
area	str	Column in obs holding cell area. When radius is None the radius becomes sqrt(area / pi). Ignored when the column is absent.	'Area'
instanceKey	str	Column in obs identifying each cell within its image. Must hold integers or strings and be unique per image; it is generated as 1..n when the column is absent.	'CellID'
regionKey	str	Column in obs to use as the SpatialData region key. Defaults to imageId when every image id is already a valid element name, and to 'region' otherwise — the sanitised names are written to that column and imageId is left untouched.	None
tableName	str	Name for the table inside the new SpatialData.	'table'
outputDir	str	When given, the store is written as <inputFilename>.zarr there — or to outputDir itself when that ends in .zarr, overwriting an existing store — and None is returned.	None
verbose	bool	Print progress messages.	True
sdataTable	str	Which table to use when data is itself a SpatialData.	None

Returns:

Name	Type	Description
sdata	SpatialData | None	The new store, or None when outputDir is given.

Raises:

Type	Description
ValueError	When obs lacks imageId, xCoordinate, or yCoordinate.

Example

# Radius derived from obs['Area'].
sdata = sp.pp.toSpatialData(adata)
sdata.tables["table"]

# Write a store instead of returning one.
sp.pp.toSpatialData(adata, outputDir="converted")

# A fixed radius, and a custom table name.
sdata = sp.pp.toSpatialData(adata, radius=5, tableName="cells")

# Everything downstream then works on the store.
sdata = sp.tl.spatialDistance(sdata, sdataTable="cells")