wsidata.WSIData

class WSIData(images=None, labels=None, shapes=None, tables=None, points=None, attrs=None, reader=None, slide_properties_source='sdata')

Bases: SpatialData

A container class combining SpatialData and a whole slide image reader.

Note

Use the open_wsi() function to create a WSIData object.

By default, the whole slide image is not attached to the SpatialData. A thumbnail version of the whole slide image is attached for visualization purpose.

Content	Default key	Slot	Type
Whole slide image	wsi_thumbnail	images	DataArray (c, y, x) format
Slide Properties	slide_properties	attrs	SlideProperties
Tissue contours	tissues	shapes	GeoDataFrame
Tile locations	tiles	shapes	GeoDataFrame
Tile specifications	tile_spec	attrs	TileSpec
Features	{feature_key}_{tile_key}	tables	AnnData

You can interact with WSIData using the following accessors:

• fetch: Access data from the WSIData object.

• iter: Iterate over data in the WSIData object.

• ds: Create deep learning datasets from the WSIData object.

• To implement your own accessors, use register_wsidata_accessor.

For analysis purpose, you can override two slide properties:

• microns per pixel (mpp): Using the set_mpp() method.

• bounds: Using the set_bounds() method.

Attributes:

propertiesSlideProperties

The properties of the whole slide image.

readerReaderBase

The reader object for interfacing with the whole slide image.

wsi_store

The zarr store path for the associated data of the whole slide image.

Other Parameters:

readerReaderBase

A reader object that can interface with the whole slide image file.

slide_properties_source{‘slide’, ‘sdata’}, default: ‘sdata’

The source of the slide properties.

• “slide”: load from the reader object.

• “sdata”: load from the SpatialData object.

property associated_images

The associated images in a key-value pair.

close()

Close the reader object.

get_thumbnail(size=500, as_array=False)

Get the thumbnail of the whole slide image.

Parameters:

as_arraybool, default: False

Return as numpy array.

property name

The file name of the whole slide image.

property properties

The properties of the whole slide image. See SlideProperties.

property raw_properties

The raw properties of the whole slide image.

read_region(x, y, width, height, level=0, **kwargs)

Read a region from the whole slide image.

Parameters:

xint

The x-coordinate at level 0.

yint

The y-coordinate at level 0.

widthint

The width of the region in pixels.

heightint

The height of the region in pixels.

levelint, default: 0

The pyramid level.

property reader

The reader object for interfacing with the whole slide image.

set_bounds(bounds)

Set the bounds of the whole slide image.

Parameters:

boundstuple[int, int, int, int]

The bounds of the whole slide image in the format [x, y, width, height].

set_exclude_elements(elements)

Set the elements to be excluded from serialize to the WSIData object on disk.

set_mpp(mpp)

Set the microns per pixel (mpp) of the whole slide image. This will override the recorded mpp in the slide properties. Could be useful when the mpp is not recorded in the image file.

Parameters:

mppfloat

The microns per pixel.

set_wsi_store(store)

Set the on disk path for the WSIData.

property thumbnail

The thumbnail of the whole slide image.

tile_spec(key)

Get the TileSpec for a collection of tiles.

Parameters:

keystr

The key of the tiles.

to_spatialdata()

Convert the WSIData object to a SpatialData object.

Note

This is not a deep copy operation. Any changes to the returned SpatialData will affect the original WSIData.

write(file_path=None, overwrite=True, consolidate_metadata=True, format=None)

Write the SpatialData object to a Zarr store.

Parameters:

file_path

The path to the Zarr store to write to.

overwrite

If True, overwrite the Zarr store if it already exists. If False, write() will fail if the Zarr store already exists.

consolidate_metadata

If True, triggers zarr.convenience.consolidate_metadata(), which writes all the metadata in a single file at the root directory of the store. This makes the data cloud accessible, which is required for certain cloud stores (such as S3).

update_sdata_path

Whether to update the path attribute of the SpatialData object to file_path after a successful write (default yes). Here are the implications.

• If True, and if the SpatialData object has dask-backed elements, the object will become “not

  self-contained” because the dask-backed element will have a path that is different from the new sdata.path attribute (now equal to file_path). By re-reading the object from disk, the object will become self-contained again.

• If False, the SpatialData object will keep its current path attribute, meaning that calling

  sdata.write_element(), sdata.write_attrs(), … will write the data to the current sdata.path location, not to the file_path location.

Please consult spatialdata.SpatialData.is_self_contained() for more information on the implications of working with self-contained and non-self-contained SpatialData objects.

sdata_formats

The format to use for writing the elements of the SpatialData object. It is recommended to leave this parameter equal to None (default to latest format for all the elements). If not None, it must be either a format for an element, or a list of formats. For example it can be a subset of the following list [RasterFormatVXX(), ShapesFormatVXX(), PointsFormatVXX(), TablesFormatVXX()]. (XX denote the version number, and should be replaced with the respective format; the version numbers can differ across elements). By default, the latest format is used for all elements, i.e. CurrentRasterFormat, CurrentShapesFormat, CurrentPointsFormat, CurrentTablesFormat. Also, by default, if a format for the SpatialData “container” object (i.e. SpatialDataContainerFormatVXX) is specified, but the format for some elements is unspecified, the element formats will be set to the latest element format compatible with the specified SpatialData container format. All the formats and relationships between them are defined in spatialdata._io.format.py.

shapes_geometry_encoding

Whether to use the WKB or geoarrow encoding for GeoParquet. See geopandas.GeoDataFrame.to_parquet() for details. If None, uses the value from spatialdata.settings.shapes_geometry_encoding.

property wsi_store

The zarr store path for the associated data of the whole slide image.