Bug when reading previously saved Xenium 2.0 data: cells without nuclei

[LucaMarconato]

The issue

Xenium 2.0 data generated with the multimodal segmentation kit may identify cells without nuclei. For such cells, due to a missing validation in ShapesModel, the presence of cells without nuclei silently caused the cell_circles shapes element to have cells with a nan value for the radius. This is now fixed and a code release is planned for the first week of August 2024. Therefore, any newly generated Xenium SpatialData will not be affected by this bug.

Nevertheless, data that has already been converted to Zarr needs to be corrected, here is how you can do it.

The fix

# please install the latest versions of spatialdata, spatialdata-io and napari-spatialdata
# you need: spatialdata > 0.2.1, spatialdata-io > v0.1.3.post0, napari-spatialdata > 0.5.0post1
# if you are reading this 
import spatialdata as sd
import numpy as np

ZARR_FILE = "/your/path/here.zarr"

sdata = sd.read_zarr(ZARR_FILE)

# default keys from the xenium() reader in spatialdata-io
CELL_CIRCLES = "cell_circles"
TABLE = "table"
CELL_ID = "cell_id"

assert CELL_CIRCLES in sdata.shapes, f"Expected {CELL_CIRCLES} in the spatial data."
assert TABLE in sdata.tables, f"Expected {TABLE} in the spatial data."

circles = sdata[CELL_CIRCLES]
table = sdata[TABLE]

radii = circles.radius
assert circles.radius.isna().sum() > 0, "There is no NaN value in the radii column that we can correct."

assert np.array_equal(
    circles.index.to_numpy(), table.obs[CELL_ID].to_numpy()
), "The indices of the circles and the table do not match, please adjust to your data."

table.obs.set_index(CELL_ID, inplace=True, drop=False)

original_cell_radii = (table.obs.cell_area / np.pi) ** 0.5
original_nucleus_radii = (table.obs.nucleus_area / np.pi) ** 0.5

nan_mask = circles.radius.isna()

assert np.allclose(
    circles.radius[~nan_mask], original_nucleus_radii.iloc[np.where(~nan_mask)[0]]
), "The non-NaN values in the radii column do not match the nucleus radii as it would be expected."
circles.radius = original_cell_radii

CELL_CIRCLES_CORRECTED = f"{CELL_CIRCLES}_corrected"
sdata[CELL_CIRCLES_CORRECTED] = circles

sdata.write_element(CELL_CIRCLES_CORRECTED)
print("done")

The code above performs various checks, if some fail it should be quick to adjust it to your data. But feel free to comment below.

You can now inspect that the data was successfully adjusted.

# you can visually verify that the correction was successful by comparing the cell and nucleus labels with the corrected
# circles and the old circles
sdata = sd.read_zarr(ZARR_FILE)
from napari_spatialdata import Interactive

Interactive(sdata)

# as last steps, you can choose to remove the original circles and rename the corrected circles to the original name;
# it's recommended to do this by simply moving the files in the zarr store (command line/terminal)

# Note: if your data needs to be placed in S3, you should then also read the data again and regenerate the consolidated
# metadata using `sdata.write_consolidated_metadata()`

The new cell circles should be larger than the previous ones because now they are (correctly) computed from the cells instead than from the nuclei (see here for an explanation scverse/spatialdata-io#123).

Also the two cells at the bottom are an example of cells for which no nuclei were detected and which resulted in circles with nan radius. Now these circles are correctly defined.

If you found this article helpful please put a "arrow up", so we can see how many users got affected. Thanks 😊