Ctrl+K

spatialdata_io.experimental.to_legacy_anndata

spatialdata_io.experimental.to_legacy_anndata#

spatialdata_io.experimental.to_legacy_anndata(sdata, coordinate_system=None, table_name=None, include_images=False)#

Convert a SpatialData object to a (legacy) spatial AnnData object.

This is useful for using packages expecting spatial information in AnnData, for example Scanpy and older versions of Squidpy. Using this format for any new package is not recommended.

This function by default ignores images (recommended); setting the include_images parameter to True will include a downscaled version of the images in the output AnnData object.

Parameters:

  • sdata (SpatialData) – SpatialData object

  • coordinate_system (str | None (default: None)) – The coordinate system to consider. The AnnData object will be populated with the data transformed to this coordinate system.

  • table_name (str | None (default: None)) – The name of the table in the SpatialData object to consider. If None and the SpatialData object has only one table, that table will be used.

  • include_images (bool (default: False)) – If True, includes downscaled versions of the images in the output AnnData object. It is recommended to handle the full resolution images separately and keep them in the SpatialData object.

Return type:

AnnData

Returns:

: The legacy spatial AnnData object.

Notes

Edge cases and limitations:

  • The Table can only annotate Shapes or Labels.

  • Labels will be approximated to circles by using the centroids of each label and an average approximated radius.

  • The Table cannot annotate more than one Shapes element. If multiple Shapes elements are present, please merge them into a single Shapes element and make the table annotate the new Shapes element.

  • Table rows not annotating geometries in the coordinate system will be dropped. Similarly, Shapes rows (in the case of Labels, the circle rows approximating the Labels) not annotated by Table rows will be dropped.

How resolutions, coordinates, indices and Table rows will be affected:

  • When include_images is True, the Images will be scaled (see later) and will not maintain the original resolution.

  • The Shapes centroids will likely change to match the alignment in the specified coordinate system, and to the images bounding boxes when include_images is True (see below).

  • The Table and Shapes rows will have the same indices as before the conversion, which is useful for plugging results back to the SpatialData object, but as mentioned above, some rows may be dropped.

When include_images is True, the generated AnnData object will contain low-resolution images and their origin will be reset to the pixel (0, 0). In particular, the ImageContainer class used by Squidpy is not used. Eventual transformations are applied before conversion. Precisely, this is how the Images are prepared for the AnnData object:

  • For each Image aligned to the specified coordinate system, the coordinate transformation to the coordinate system is applied; all the Images are rendered to a common target bounding box, which is the bounding box of the union of the Images aligned to the target coordinate system.

  • The origins of the new images will match the pixel (0, 0) of the target bounding box.

  • Each Image is downscaled (or upscaled) during rendering to fit a 2000x2000 pixels image (downscaled_hires) and a 600x600 pixels image (downscaled_lowres).

  • Practically the above implies that if the Images have very dissimilar locations, most the rendered Images will have empty spaces; in such cases it is recommended to drop or crop some images before the conversion.

Matching of spatial coordinates and pixel coordinates:

  • When include_images is True, the coordinates in obsm['spatial'] will match the downscaled (generated) image “hires” (i.e. coordinate (x, y) will match with the pixel (y, x) in the image). Please note that the “hires” naming is used for legacy reasons, but the image is actually downscaled and fairly low resolution.

  • The above matching is not perfect due to this bug: scverse/spatialdata#165, which will eventually be addressed.

Imperfect downscaling:

  • Due to the bug mentioned above, scverse/spatialdata#165, when the downscaling factor is large, the error between the original and the downscale image can be significant. This is another reason to not recommend using include_images=True. Note, however, that the error can be large only between the original and the downscaled images, not between the downscaled images and the new spatial coordinates. Thus the use may be acceptable for some use cases.

Final consideration:

  • Due to the legacy nature of the AnnData object generated, this function may not handle all the edge cases, please report any issue you may find.

Contents