Add support for Space Ranger cell segmentation data

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

@asmlgkj

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

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.

@asmlgkj

@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.

@timtreis

@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.

@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

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.

@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.

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

@stephenwilliams22

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.

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.

@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

@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

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

@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

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)
        }
    }
}

@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

@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

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!

@hannahaichelman

@hannahaichelman I've updated the notebook to include import of spatialdata_plot which you'll need for the pl command. Also, to the top of the notebook I updated the install instructions to keep you up to date

The load_segmentation_only parameter skips bin import (which is probably what I would do). when you installed from commit hash 531769a you installed an older version of spatialdata-io which didn't include that param.

Hopefully you should be good to go now!

@stephenwilliams22

@hannahaichelman I've updated the notebook to include import of spatialdata_plot which you'll need for the pl command. Also, to the top of the notebook I updated the install instructions to keep you up to date

The load_segmentation_only parameter skips bin import (which is probably what I would do). when you installed from commit hash 531769a you installed an older version of spatialdata-io which didn't include that param.

Hopefully you should be good to go now!

Hi @stephenwilliams22 - sorry for this but I am still having some trouble getting this to work. Double checking that the notebook you updated is here: https://github.com/scverse/spatialdata-notebooks/blob/61b97d8f10722f297f0a3c94a9b6417d41866bd7/notebooks/examples/visium_hd_mouse_brain.ipynb?

I just don't see the updated import of spatialdata_plot or install instructions, which is why I ask. And I am unsure of the best way to install the commit with the updated function if not from the commit has 531769a. Sorry again if I'm missing something simple!

@hannahaichelman

@hannahaichelman I've updated the notebook to include import of spatialdata_plot which you'll need for the pl command. Also, to the top of the notebook I updated the install instructions to keep you up to date
The load_segmentation_only parameter skips bin import (which is probably what I would do). when you installed from commit hash 531769a you installed an older version of spatialdata-io which didn't include that param.
Hopefully you should be good to go now!

Hi @stephenwilliams22 - sorry for this but I am still having some trouble getting this to work. Double checking that the notebook you updated is here: https://github.com/scverse/spatialdata-notebooks/blob/61b97d8f10722f297f0a3c94a9b6417d41866bd7/notebooks/examples/visium_hd_mouse_brain.ipynb?

I just don't see the updated import of spatialdata_plot or install instructions, which is why I ask. And I am unsure of the best way to install the commit with the updated function if not from the commit has 531769a. Sorry again if I'm missing something simple!

@hannahaichelman no the notebook is here https://github.com/scverse/spatialdata-notebooks/blob/29efb70915be337781b5c5cf354040e79579ad5e/notebooks/examples/visium_hd_mouse_brain.ipynb. You can always view the latest notebook by clicking on Files changed in GH, then clicking on the ... button, and pressing view file

You'll see a new section at the top which show how to properly install the correct branch and import spatialdata_plot # noqa: F401 in the first python cell

@hannahaichelman I've updated the notebook to include import of spatialdata_plot which you'll need for the pl command. Also, to the top of the notebook I updated the install instructions to keep you up to date
The load_segmentation_only parameter skips bin import (which is probably what I would do). when you installed from commit hash 531769a you installed an older version of spatialdata-io which didn't include that param.
Hopefully you should be good to go now!

Hi @stephenwilliams22 - sorry for this but I am still having some trouble getting this to work. Double checking that the notebook you updated is here: https://github.com/scverse/spatialdata-notebooks/blob/61b97d8f10722f297f0a3c94a9b6417d41866bd7/notebooks/examples/visium_hd_mouse_brain.ipynb?
I just don't see the updated import of spatialdata_plot or install instructions, which is why I ask. And I am unsure of the best way to install the commit with the updated function if not from the commit has 531769a. Sorry again if I'm missing something simple!

@hannahaichelman no the notebook is here https://github.com/scverse/spatialdata-notebooks/blob/29efb70915be337781b5c5cf354040e79579ad5e/notebooks/examples/visium_hd_mouse_brain.ipynb. You can always view the latest notebook by clicking on Files changed in GH, then clicking on the ... button, and pressing view file

You'll see a new section at the top which show how to properly install the correct branch and import spatialdata_plot # noqa: F401 in the first python cell

Perfect, thanks so much. The load function is working now I appreciate your help!

Thanks for the discussion! Closing as the updated reader has been made available in spatialdata-io in v0.5.0, and an example notebook can be found here scverse/spatialdata-tutorials#152 (it will appear in the docs with the next release).

Navigation Menu

Repository navigation

Add support for Space Ranger cell segmentation data #323

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add support for Space Ranger cell segmentation data #323

Description

Activity

timtreis commented on Sep 13, 2025

asmlgkj commented on Sep 13, 2025

stephenwilliams22 commented on Sep 16, 2025

asmlgkj commented on Sep 18, 2025

hannahaichelman commented on Sep 29, 2025

stephenwilliams22 commented on Sep 30, 2025

stephenwilliams22 commented on Oct 1, 2025

LucaMarconato commented on Oct 2, 2025

LucaMarconato commented on Oct 2, 2025

stephenwilliams22 commented on Oct 6, 2025

hannahaichelman commented on Oct 7, 2025

hannahaichelman commented on Oct 15, 2025

stephenwilliams22 commented on Oct 16, 2025

hannahaichelman commented on Oct 17, 2025

stephenwilliams22 commented on Oct 17, 2025

hannahaichelman commented on Oct 22, 2025

stephenwilliams22 commented on Oct 22, 2025

hannahaichelman commented on Oct 22, 2025

LucaMarconato commented on Dec 23, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions