Stereoseq expected directory structure

Hi Team,

Would it be possible to document the expected directory structure for the stereoseq reader? The results we got from the stereoseq team don't follow the directory structure being assumed by this implementation. So, if it's properly documented, like the folder names to expect and which files should be put in which folder, then we can manually restructure our directories to conform to this stereoseq reader implementation.

As an example, this is the results folder we receive from the Stereoseq team:

Thanks a bunch.

@aadimator

Thanks @aadimator for reporting this. @LLehner could you please have a look into this?

Precisely, please I would add a line in the docstring of the stereoseq function specifying which stereoseq data version we expected and adding a link to the technical document from the STOmics website that specifies the file structure.

@aadimator which version of the data is the screenshot referring to?

This comment: #70 (comment) is from July 31st, 2023, therefore I believe that the reader is designed for the format 7.0.0: https://github.com/STOmics/SAW/tree/0808e44619f84b67d44c063b2fd24762f6633051/Documents/FileFormat and that the latest 7.1.1 (or even 7.1.0) is not supported.

@aadimator

Thanks @aadimator for reporting this. @LLehner could you please have a look into this?

Precisely, please I would add a line in the docstring of the stereoseq function specifying which stereoseq data version we expected and adding a link to the technical document from the STOmics website that specifies the file structure.

@aadimator which version of the data is the screenshot referring to?

We got this as is from the Stereoseq Team, and I think it's not following any particular format. I think I'll have to manually rename/place the files into their relative/expected directories. I'll try to follow the SAW 7.0.0. format for now.

saw 8.0 has new output directory structure

from this manual:
https://en.stomics.tech/service/new-saw-operation-manual.html

Thank you for the comment. For the moment I will restrict or document that the reader operates only on 7.x. Unfortunately we don't have the bandwidth to support the latest version at the moment. But a community contribution is welcomed and we would be happy to review the code in such case.

Todo for us:

restrict or document that the stereoseq reader only works for 7.x data.

scverse#161 stereoseq v8

@z-spider

Hi Luca,
I tried https://github.com/brainfo/spatialdata-io/blob/main/src/spatialdata_io/readers/stereoseq.py

This works with the "folder structure" from SAW v8; for also a duplicate issue #322

Side note 1: datasets from stormics website are not with a folder structure but files all in one directory https://en.stomics.tech/col1357/index ; to test on output folder structure from SAW v8, we could create such structure and put the data from the website. For now I tested on in-house data, showed following replaced the real id to {sample_id}

Side note 2: In my practice, actually, for collaboration project, we only transfer necessary data, but not the entire folder structure where @z-spider copied. Unnecessary folder and files are: bam/; feature_expression/{sample_id}.raw.gef; feature_expression/.txt; analysis/.marker_features.csv; visualization.tar.gz*; {sample_id}.report.html); doesn't hurt to keep them, i.e., the outs/ folder intact with all files. Below is a minimal example:

outs
├── analysis *optional when load_analysis=False
│   ├── {sample_id}.bin20_1.0.h5ad 
│   └── {sample_id}.bin50_1.0.h5ad
├── feature_expression
│   └── {sample_id}.tissue.gef *required
└── image *optional
    ├── {sample_id}_HE_regist.tif
    └── {sample_id}_HE_tissue_cut.tif

4 directories, 5 files

from spatialdata_io import stereoseq_v8
sdata = stereoseq_v8('path/to/outs') # outs/ in the saw8 output directory

then I got an sdata

SpatialData object
├── Images
│     ├── '{sample_id}_HE_regist': DataTree[cyx] (3, 23520, 23520), (3, 11760, 11760), (3, 5880, 5880), (3, 2940, 2940), (3, 1470, 1470)
│     └── '{sample_id}_HE_tissue_cut': DataTree[cyx] (1, 23520, 23520), (1, 11760, 11760), (1, 5880, 5880), (1, 2940, 2940), (1, 1470, 1470)
├── Points
│     ├── 'analysis_bin20_points': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'analysis_bin50_points': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin1_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin5_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin10_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin20_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin50_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin100_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     ├── 'bin150_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
│     └── 'bin200_genes': DataFrame with shape: (<Delayed>, 2) (2D points)
└── Tables
      ├── 'analysis_bin20': AnnData (199772, 28999)
      ├── 'analysis_bin50': AnnData (33366, 28999)
      ├── 'bin1_table': AnnData (2636982, 28999)
      ├── 'bin5_table': AnnData (1496312, 28999)
      ├── 'bin10_table': AnnData (652510, 28999)
      ├── 'bin20_table': AnnData (199772, 28999)
      ├── 'bin50_table': AnnData (33366, 28999)
      ├── 'bin100_table': AnnData (8575, 28999)
      ├── 'bin150_table': AnnData (3888, 28999)
      └── 'bin200_table': AnnData (2241, 28999)
with coordinate systems:
    ▸ 'global', with elements:
        {sample_id}_HE_regist (Images), {sample_id}_HE_tissue_cut (Images), analysis_bin20_points (Points), analysis_bin50_points (Points), bin1_genes (Points), bin5_genes (Points), bin10_genes (Points), bin20_genes (Points), bin50_genes (Points), bin100_genes (Points), bin150_genes (Points), bin200_genes (Points)

Hi, great to hear that you found a workaround. Thanks for sharing!

scverse#161 stereoseq v8

Question is this still something that someone wants worked on?

While I usually load directly from cell bins or specific bin size I am using for analysis.
I have believe I have a script that can handle input directly saw 8.2* and I have more than enough internal data to test on.

Let me know and I will work on updating the script a function to contribute.

@akcasasent

Hi @akcasasent, unfortunately we don't have the capacity at the moment to expand the stereoseq reader. In general we are trying to keep the focus upstream (spatialdata) rather than spatialdata-io since achieving a more stable and better documented data format would simplify data ingestions and even remove the need for a library like spatialdata-io in the long term (commercial platform could directly out a SpatialData object once the format is mature).

Regarding your script, I believe that it would be useful for other users. An option would be to publish a reader in a separate repo from spatialdata-io. We can still point to your code in our Readme, adding a link to your repo to the text "Only Stereo-seq 7.x is supported, 8.x is not currently supported. #161". Or if you prefer you can also add the code directly in this issue since it is easily discoverable from the Readme.

@LucaMarconato

Hi @LucaMarconato,

I was actually offering to assist in writing / expanding the stereoseq reader both to handle 8.x and handle microbiome.

It seems like you would prefer it in a separate repo which is fine. I will finish it and then link it here once I have tested it a few ways. I have a project I am working on where I have to have it handle the omni microbiome options as well as GEX standard spatial bins and cell bins options. So, I will be creating a function anyway. :-) I just joined the scverse community and am planning to contribute some where people need it. Hence the offer. I have used scverse for a while, but my current job it happy with me working on analysis and contributing here as well.

~AKC

@akcasasent

@akcasasent hi, do you have time to share, thanks a lot

@asmlgkj

@akcasasent hi, do you have time to share, thanks a lot

@asmlgkj yes. I will share on Monday. Sorry about the delay.

@akcasasent hi, do you have time to share, thanks a lot

@asmlgkj yes. I will share on Monday. Sorry about the delay.

Thanks a lot. I just used scanpy now. not spatialdata-io to do the task

Navigation Menu

Repository navigation

Stereoseq expected directory structure #161

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Stereoseq expected directory structure #161

Description

Activity

LucaMarconato commented on Jul 10, 2024

LucaMarconato commented on Jul 10, 2024

aadimator commented on Aug 1, 2024

z-spider commented on Aug 7, 2024

LucaMarconato commented on Aug 7, 2024

brainfo commented on Oct 14, 2025

LucaMarconato commented on Oct 15, 2025

akcasasent commented on Jun 21, 2026

LucaMarconato commented on Jun 23, 2026

akcasasent commented on Jun 23, 2026

asmlgkj commented on Jul 6, 2026

akcasasent commented on Jul 11, 2026

asmlgkj commented on Jul 11, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions