Add support for Space Ranger cell segmentation data

[asmlgkj]

What kind of feature would you like to request?
Additional function parameters / changed functionality / changed defaults?

Please describe your wishes
will scanpy add support for this
thanks a lot.
because sc.pl.spatial will throw error
-> 1311 return spatial_data["scalefactors"]["spot_diameter_fullres"]
1312 else:
1313 return spot_size

KeyError: 'spot_diameter_fullres'

a typical scalefactor_json.json file (that I used to analyze) as follows:
{
"microns_per_pixel": 0.2637383875630947,
"tissue_lowres_scalef": 0.011981168,
"fiducial_diameter_fullres": 1206.530590494683,
"tissue_hires_scalef": 0.11981167,
"regist_target_img_scalef": 0.11981167
}
thanks a lot

[timtreis]

Hey @asmlgkj, could you give some more details on what you did and you're trying to achieve?

[asmlgkj]

thanks a lot, the 10x genomics now gives cell segmentation results, not like visium hd data style, I want to spatialdata-io can read and deal with it ,like in https://www.10xgenomics.com/analysis-guides/segmentation-visium-hd. seurat now can deal with it, a python package https://github.com/seqyuan/trackcell can read it, but it failed like in seqyuan/trackcell#1

I may should creat this issue in https://github.com/scverse/squidpy/issues, I am so sorry.

[stephenwilliams22]

@asmlgkj Just wanted to let you know that we're on top of this. I'm hoping to have a PR up on spatialdata-io in the next day or so.

[asmlgkj]

@timtreis
@stephenwilliams22
thanks a lot. I sovle it by a leson from 10x genomics. also used your packages (spatialdata-io) read and save data.

I have a couple of questions regarding the SpatialData outputs and how cell positions are represented in Seurat objects:

SpatialData outputs:
When using SpatialData, the results (image and expression) are stored as separate elements. However, this makes it more difficult to interface with downstream tools such as Squidpy, which often rely on each cell (or observation) having an associated spatial coordinate. Similarly, visualization tools that expect an H&E image may fail if the AnnData/Seurat object does not directly contain the image.

What is the recommended way to ensure compatibility with such tools?

Should we be explicitly merging the image and expression layers, or is there a standard workflow for linking them?

Polygon-based cells:
For segmented cells represented by polygons, a single representative point is often required for certain downstream analyses (e.g., co-localization, neighbor graphs).

Does Seurat currently use the geometric centroid of each polygon, or some other representative location?

In cases where the centroid falls outside of the polygon (e.g., crescent-shaped or elongated cells), would you recommend using the centroid, or instead an interior point (such as st_point_on_surface in sf)?

I would greatly appreciate your advice on best practices here, as this has important implications for interoperability with Squidpy and other spatial analysis or visualization software.

[hannahaichelman]

Hi @stephenwilliams22 - wanted to check in and see if there are any updates to this, I just got some Visium HD 3' data back and am curious if there is a streamlined way to read in the cell segmented outputs. Thank you!

[stephenwilliams22]

Hi @stephenwilliams22 - wanted to check in and see if there are any updates to this, I just got some Visium HD 3' data back and am curious if there is a streamlined way to read in the cell segmented outputs. Thank you!

@hannahaichelman a PR is incoming very soon. I'm going to try and push it today or tomorrow at the latest.

[stephenwilliams22]

@timtreis @stephenwilliams22 thanks a lot. I sovle it by a leson from 10x genomics. also used your packages (spatialdata-io) read and save data.

I have a couple of questions regarding the SpatialData outputs and how cell positions are represented in Seurat objects:

SpatialData outputs: When using SpatialData, the results (image and expression) are stored as separate elements. However, this makes it more difficult to interface with downstream tools such as Squidpy, which often rely on each cell (or observation) having an associated spatial coordinate. Similarly, visualization tools that expect an H&E image may fail if the AnnData/Seurat object does not directly contain the image.

What is the recommended way to ensure compatibility with such tools?

Should we be explicitly merging the image and expression layers, or is there a standard workflow for linking them?

Polygon-based cells: For segmented cells represented by polygons, a single representative point is often required for certain downstream analyses (e.g., co-localization, neighbor graphs).

Does Seurat currently use the geometric centroid of each polygon, or some other representative location?

In cases where the centroid falls outside of the polygon (e.g., crescent-shaped or elongated cells), would you recommend using the centroid, or instead an interior point (such as st_point_on_surface in sf)?

I would greatly appreciate your advice on best practices here, as this has important implications for interoperability with Squidpy and other spatial analysis or visualization software.

Hi @asmlgkj I'll leave the broader questions for the official scverse team but try to answer specific questions the best that I can.

Polygon-based cells: For segmented cells represented by polygons, a single representative point is often required for certain downstream analyses (e.g., co-localization, neighbor graphs).

The 10x specific outputs do not contain a centroid for such analyses but they can easily be calculated from the polygons and saved in the spatialdata object. I'll work with the spatialdata-io team on getting the centroid build in as part of the notebook which will accompany the support for cell segmentation PR

Does Seurat currently use the geometric centroid of each polygon, or some other representative location?

This question should be directed to the Seurat PR here satijalab/seurat#10028

[LucaMarconato]

Thanks for the answers @stephenwilliams22. @asmlgkj since the questions you asked are off-topic in this issue, I moved the conversation here: https://discourse.scverse.org/t/questions-on-shapes-tables-vs-single-anndata-object/3814. I will follow up there. In the future please open a discussion in Zulip/Discourse, or in separate GitHub issues.

[LucaMarconato]

The 10x specific outputs do not contain a centroid for such analyses but they can easily be calculated from the polygons and saved in the spatialdata object. I'll work with the spatialdata-io team on getting the centroid build in as part of the notebook which will accompany the support for cell segmentation PR

Sounds great, thanks! You may find the get_centroids() API useful in case you want to quickly calculate them also for raster data (labels) or across coordinate systems.

[stephenwilliams22]

Hi @stephenwilliams22 - wanted to check in and see if there are any updates to this, I just got some Visium HD 3' data back and am curious if there is a streamlined way to read in the cell segmented outputs. Thank you!

@hannahaichelman Please see PR here. Comments are welcome and hopefully this should get you going #328

[hannahaichelman]

Hi @stephenwilliams22 - wanted to check in and see if there are any updates to this, I just got some Visium HD 3' data back and am curious if there is a streamlined way to read in the cell segmented outputs. Thank you!

@hannahaichelman Please see PR here. Comments are welcome and hopefully this should get you going #328

Amazing, thanks so much @stephenwilliams22 I will give this a shot!

[hannahaichelman]

Hi @stephenwilliams22 - wanted to check in and see if there are any updates to this, I just got some Visium HD 3' data back and am curious if there is a streamlined way to read in the cell segmented outputs. Thank you!

@hannahaichelman Please see PR here. Comments are welcome and hopefully this should get you going #328

Amazing, thanks so much @stephenwilliams22 I will give this a shot!

Hi again @stephenwilliams22 - I've had a chance to test this out and it is working great for the most part. The only issues I am encountering are related to the spatial coordinates and size factors in the spatial data object that is generated. I've been able to add them both in manually, using the spatialdata.get_centroids() function for coordinates and the code included below for size factors, but curious if this is something that could be added in to the function? Or maybe I'm missing something, happy to provide more context for what I've tried. Thanks again for your help with this!

adata_cell_seg.uns['spatial'] = {
    'spatial': {
        'scalefactors': {
            'spot_diameter_fullres': 1904.144084291308,  
            'tissue_hires_scalef': 0.13269933,     
            'tissue_lowres_scalef': 0.013269933     
        },
        'images': {
            'hires': np.array(hires_image)
        }
    }
}

[stephenwilliams22]

Hi again @stephenwilliams22 - I've had a chance to test this out and it is working great for the most part. The only issues I am encountering are related to the spatial coordinates and size factors in the spatial data object that is generated. I've been able to add them both in manually, using the spatialdata.get_centroids() function for coordinates and the code included below for size factors, but curious if this is something that could be added in to the function? Or maybe I'm missing something, happy to provide more context for what I've tried. Thanks again for your help with this!

adata_cell_seg.uns['spatial'] = {
    'spatial': {
        'scalefactors': {
            'spot_diameter_fullres': 1904.144084291308,  
            'tissue_hires_scalef': 0.13269933,     
            'tissue_lowres_scalef': 0.013269933     
        },
        'images': {
            'hires': np.array(hires_image)
        }
    }
}

Thanks for the comment @hannahaichelman. I'm not 100% sure why you need the the scalefactors in the spatialdata object considering you've got the transformed coordinate systems in the object already. Can you provided a bit more context? Not sure if you saw this example I submitted but you can find it here. it takes you from loading data all the way through plotting, simple QC, clustering, centroid identification, etc. https://github.com/scverse/spatialdata-notebooks/blob/61b97d8f10722f297f0a3c94a9b6417d41866bd7/notebooks/examples/visium_hd_mouse_brain.ipynb

[hannahaichelman]

Hi again @stephenwilliams22 - I've had a chance to test this out and it is working great for the most part. The only issues I am encountering are related to the spatial coordinates and size factors in the spatial data object that is generated. I've been able to add them both in manually, using the spatialdata.get_centroids() function for coordinates and the code included below for size factors, but curious if this is something that could be added in to the function? Or maybe I'm missing something, happy to provide more context for what I've tried. Thanks again for your help with this!

adata_cell_seg.uns['spatial'] = {
    'spatial': {
        'scalefactors': {
            'spot_diameter_fullres': 1904.144084291308,  
            'tissue_hires_scalef': 0.13269933,     
            'tissue_lowres_scalef': 0.013269933     
        },
        'images': {
            'hires': np.array(hires_image)
        }
    }
}

Thanks for the comment @hannahaichelman. I'm not 100% sure why you need the the scalefactors in the spatialdata object considering you've got the transformed coordinate systems in the object already. Can you provided a bit more context? Not sure if you saw this example I submitted but you can find it here. it takes you from loading data all the way through plotting, simple QC, clustering, centroid identification, etc. https://github.com/scverse/spatialdata-notebooks/blob/61b97d8f10722f297f0a3c94a9b6417d41866bd7/notebooks/examples/visium_hd_mouse_brain.ipynb

Hi @stephenwilliams22 - thank you for pointing me to the notebook example, I hadn't seen that. After reviewing it, I am now not sure that I have the correct version of spatialdata-io installed from your PR, but let me give you some more context.

In my first attempt, I used your sdio.visium_hd function to read in my data, which produced an object with this structure:

SpatialData object
├── Images
│     ├── '_full_image': DataTree[cyx] (3, 44564, 36863), (3, 22282, 18431), (3, 11141, 9215), (3, 5570, 4607), (3, 2785, 2303)
│     ├── '_hires_image': DataArray[cyx] (3, 6000, 4963)
│     └── '_lowres_image': DataArray[cyx] (3, 600, 497)
├── Shapes
│     ├── '_cell_segmentations': GeoDataFrame shape: (97453, 2) (2D shapes)
│     └── '_nucleus_segmentations': GeoDataFrame shape: (96942, 2) (2D shapes)
└── Tables
      ├── 'cell_segmentations': AnnData (97453, 62887)
      └── 'nucleus_segmentations': AnnData (96942, 62887)
with coordinate systems:
    ▸ '', with elements:
        _full_image (Images)
    ▸ '_downscaled_hires', with elements:
        _hires_image (Images), _cell_segmentations (Shapes), _nucleus_segmentations (Shapes)
    ▸ '_downscaled_lowres', with elements:
        _lowres_image (Images), _cell_segmentations (Shapes), _nucleus_segmentations (Shapes)

However, when I try to follow your notebook and plot the images I get this error:
AttributeError: 'SpatialData' object has no attribute 'pl'

Next, I tried re-installing to make sure I was using the specific commit version in my virtual environment, which I did with this command:
pip install "git+https://github.com/scverse/spatialdata-io.git@531769a7f"

While the version of spatialdata-io that I installed matches the version listed in your notebook example (spatialdata_io==0.3.1.dev22+g531769a7f), the version of the sdio.visium_hd function doesn't seem right, as it doesn't include the option for 'load_segmentations_only' and I get this error:
TypeError: visium_hd() got an unexpected keyword argument 'load_segmentations_only'

Apologies if I'm missing something really simple here, but any advice you can provide would be great. Thank you!