Skip to content

Commit dff616a

Browse files
committed
scverse#161 stereoseq v8
1 parent 638677a commit dff616a

3 files changed

Lines changed: 4756 additions & 2 deletions

File tree

‎src/spatialdata_io/__init__.py‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
from spatialdata_io.readers.merscope import merscope
1212
from spatialdata_io.readers.seqfish import seqfish
1313
from spatialdata_io.readers.steinbock import steinbock
14-
from spatialdata_io.readers.stereoseq import stereoseq
14+
from spatialdata_io.readers.stereoseq import stereoseq, stereoseq_v8
1515
from spatialdata_io.readers.visium import visium
1616
from spatialdata_io.readers.visium_hd import visium_hd
1717
from spatialdata_io.readers.xenium import (
@@ -31,6 +31,7 @@
3131
"seqfish",
3232
"steinbock",
3333
"stereoseq",
34+
"stereoseq_v8",
3435
"visium",
3536
"visium_hd",
3637
"xenium",

‎src/spatialdata_io/readers/stereoseq.py‎

Lines changed: 299 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
if TYPE_CHECKING:
2626
from collections.abc import Mapping
2727

28-
__all__ = ["stereoseq"]
28+
__all__ = ["stereoseq", "stereoseq_v8"]
2929

3030

3131
@inject_docs(xx=SK)
@@ -340,3 +340,301 @@ def stereoseq(
340340

341341
sdata = SpatialData(images=images, tables=tables, shapes=shapes, points=points)
342342
return sdata
343+
344+
345+
@inject_docs(xx=SK)
346+
def stereoseq_v8(
347+
path: str | Path,
348+
dataset_id: str | None = None,
349+
bin_sizes: list[int] | None = None,
350+
load_analysis: bool = True,
351+
imread_kwargs: Mapping[str, Any] = MappingProxyType({}),
352+
image_models_kwargs: Mapping[str, Any] = MappingProxyType({}),
353+
) -> SpatialData:
354+
"""Read *Stereo-seq* formatted dataset from SAW v8 pipeline.
355+
356+
This function supports the output structure from SAW (Stereo-seq Analysis Workflow) version 8,
357+
which differs from version 7 in directory organization and available data types.
358+
359+
Parameters
360+
----------
361+
path
362+
Path to the directory containing the SAW v8 output data.
363+
dataset_id
364+
Dataset identifier. If not given will be determined automatically from file names.
365+
bin_sizes
366+
List of bin sizes to read from the tissue.gef file (e.g., [1, 20, 50, 100]).
367+
If None, reads all available bin sizes. Common bins are 1, 5, 10, 20, 50, 100, 150, 200.
368+
load_analysis
369+
If True, will load pre-computed analysis results (h5ad files) from the analysis directory.
370+
These typically contain clustering, dimensionality reduction, and other analysis results.
371+
imread_kwargs
372+
Keyword arguments passed to :func:`dask_image.imread.imread`.
373+
image_models_kwargs
374+
Keyword arguments passed to :class:`spatialdata.models.Image2DModel`.
375+
376+
Returns
377+
-------
378+
:class:`spatialdata.SpatialData`
379+
380+
Notes
381+
-----
382+
SAW v8 Structure:
383+
- feature_expression/: Contains .raw.gef and .tissue.gef files with gene expression data
384+
- analysis/: Contains pre-computed h5ad files with clustering and analysis results
385+
- image/: Contains H&E images (_HE_regist.tif and _HE_tissue_cut.tif)
386+
- bam/: Contains alignment files (not parsed by this function)
387+
388+
The tissue.gef file contains binned gene expression data at multiple resolutions (bin1, bin20, etc.),
389+
while the analysis folder contains downstream analysis results.
390+
"""
391+
image_models_kwargs, _ = _initialize_raster_models_kwargs(image_models_kwargs, {})
392+
path = Path(path)
393+
394+
# Determine dataset_id if not provided
395+
if dataset_id is None:
396+
feature_exp_path = path / "feature_expression"
397+
if not feature_exp_path.exists():
398+
raise ValueError(f"feature_expression directory not found in {path}")
399+
400+
# Find .tissue.gef file to extract dataset_id
401+
gef_files = list(feature_exp_path.glob("*.tissue.gef"))
402+
if not gef_files:
403+
raise ValueError(f"No .tissue.gef files found in {feature_exp_path}")
404+
405+
# Extract dataset_id from filename (e.g., B05062E4.tissue.gef -> B05062E4)
406+
dataset_id = gef_files[0].stem.replace(".tissue", "")
407+
408+
# Define file paths
409+
tissue_gef_path = path / "feature_expression" / f"{dataset_id}.tissue.gef"
410+
image_dir = path / "image"
411+
analysis_dir = path / "analysis"
412+
413+
if not tissue_gef_path.exists():
414+
raise ValueError(f"tissue.gef file not found: {tissue_gef_path}")
415+
416+
# Read tissue.gef file
417+
tissue_gef = h5py.File(str(tissue_gef_path), "r")
418+
419+
# Determine which bin sizes to read
420+
available_bins = list(tissue_gef[SK.GENE_EXP].keys())
421+
if bin_sizes is None:
422+
bins_to_read = available_bins
423+
else:
424+
bins_to_read = [f"bin{size}" for size in bin_sizes]
425+
# Validate that requested bins exist
426+
missing_bins = set(bins_to_read) - set(available_bins)
427+
if missing_bins:
428+
raise ValueError(
429+
f"Requested bin sizes {missing_bins} not found in tissue.gef. "
430+
f"Available bins: {available_bins}"
431+
)
432+
433+
# Initialize containers
434+
images = {}
435+
tables = {}
436+
points = {}
437+
438+
# Read images
439+
if image_dir.exists():
440+
image_patterns = [
441+
re.compile(r".*_HE_regist\.tif$"),
442+
re.compile(r".*_HE_tissue_cut\.tif$"),
443+
]
444+
image_files = [
445+
f for f in os.listdir(image_dir)
446+
if any(pattern.match(f) for pattern in image_patterns)
447+
]
448+
449+
for image_file in image_files:
450+
image_name = Path(image_file).stem
451+
# Use appropriate dims based on what imread returns
452+
# For RGB images, imread typically returns (z, y, x, c) format
453+
# We'll let Image2DModel handle the conversion by not specifying dims
454+
img_data = imread(image_dir / image_file, **imread_kwargs)
455+
456+
# For SAW v8, images are RGB TIFFs in (1, y, x, 3) format from imread
457+
# We need to convert to (c, y, x) - squeeze and move channels to first dim
458+
if img_data.ndim == 4 and img_data.shape[0] == 1:
459+
# Remove singleton first dimension and move channels from last to first
460+
img_data = img_data[0] # Now (y, x, c)
461+
462+
# Now transpose from (y, x, c) to (c, y, x)
463+
if img_data.ndim == 3 and img_data.shape[-1] in [1, 3, 4]: # Last dim is channels
464+
img_data = np.moveaxis(img_data, -1, 0) # Move last axis to first
465+
466+
images[image_name] = Image2DModel.parse(
467+
img_data,
468+
dims=("c", "y", "x"),
469+
**image_models_kwargs,
470+
)
471+
472+
# Read binned gene expression data from tissue.gef
473+
for bin_name in bins_to_read:
474+
bin_group = tissue_gef[SK.GENE_EXP][bin_name]
475+
bin_attrs = dict(bin_group[SK.EXPRESSION].attrs)
476+
resolution = bin_attrs[SK.RESOLUTION].item()
477+
478+
# Get gene information
479+
gene_data = bin_group[SK.FEATURE_KEY][:]
480+
df_gene = pd.DataFrame(
481+
gene_data,
482+
columns=["geneID", SK.GENE_NAME, SK.OFFSET, SK.COUNT]
483+
)
484+
df_gene["geneID"] = df_gene["geneID"].str.decode("utf-8")
485+
df_gene[SK.GENE_NAME] = df_gene[SK.GENE_NAME].str.decode("utf-8")
486+
487+
# Handle duplicate gene names by making them unique
488+
# Some genes have the same name but different IDs (e.g., different isoforms)
489+
df_gene["gene_name_unique"] = df_gene[SK.GENE_NAME]
490+
duplicated_mask = df_gene[SK.GENE_NAME].duplicated(keep=False)
491+
if duplicated_mask.any():
492+
# For duplicates, append gene ID to make unique
493+
df_gene.loc[duplicated_mask, "gene_name_unique"] = (
494+
df_gene.loc[duplicated_mask, SK.GENE_NAME] + "_" +
495+
df_gene.loc[duplicated_mask, "geneID"]
496+
)
497+
498+
# Get expression data (x, y, count)
499+
expression_data = bin_group[SK.EXPRESSION][:]
500+
df_points = pd.DataFrame(
501+
expression_data,
502+
columns=[SK.COORD_X, SK.COORD_Y, SK.COUNT]
503+
)
504+
505+
# Validate offset calculation
506+
assert np.array_equal(
507+
df_gene[SK.OFFSET],
508+
np.insert(np.cumsum(df_gene[SK.COUNT]), 0, 0)[:-1]
509+
)
510+
511+
# Unroll gene names by count to match coordinate counts
512+
# Use unique gene names to avoid issues with duplicates
513+
df_points[SK.FEATURE_KEY] = [
514+
name
515+
for _, (name, cell_count) in df_gene[["gene_name_unique", SK.COUNT]].iterrows()
516+
for _ in range(cell_count)
517+
]
518+
df_points[SK.FEATURE_KEY] = df_points[SK.FEATURE_KEY].astype("category")
519+
520+
# Create unique bin IDs
521+
points_coords = df_points[[SK.COORD_X, SK.COORD_Y]].copy()
522+
points_coords.drop_duplicates(inplace=True)
523+
points_coords.reset_index(inplace=True, drop=True)
524+
points_coords["bin_id"] = points_coords.index
525+
526+
name_points_element = f"{bin_name}_genes"
527+
name_table_element = f"{bin_name}_table"
528+
529+
# Map each point to its bin_id
530+
index_to_bin_id = pd.merge(
531+
df_points[[SK.COORD_X, SK.COORD_Y]],
532+
points_coords,
533+
on=[SK.COORD_X, SK.COORD_Y],
534+
how="left",
535+
validate="many_to_one",
536+
)
537+
538+
# Create obs for AnnData
539+
obs = pd.DataFrame({
540+
SK.INSTANCE_KEY: points_coords.index,
541+
SK.REGION_KEY: name_points_element
542+
})
543+
obs[SK.REGION_KEY] = obs[SK.REGION_KEY].astype("category")
544+
545+
# Create expression matrix as sparse matrix
546+
expression_matrix = coo_matrix(
547+
(
548+
df_points[SK.COUNT],
549+
(
550+
index_to_bin_id.loc[df_points.index]["bin_id"].to_numpy(),
551+
df_points[SK.FEATURE_KEY].cat.codes
552+
),
553+
),
554+
shape=(len(points_coords), len(df_points[SK.FEATURE_KEY].cat.categories)),
555+
).tocsr()
556+
557+
# Create points element
558+
points_coords.drop(columns=["bin_id"], inplace=True)
559+
points_element = PointsModel.parse(
560+
points_coords,
561+
coordinates={"x": SK.COORD_X, "y": SK.COORD_Y},
562+
)
563+
564+
# Prepare gene info for var
565+
# Only keep genes that have expression data in this bin
566+
genes_with_expression = df_points[SK.FEATURE_KEY].cat.categories
567+
df_gene_indexed = df_gene.set_index("gene_name_unique")
568+
df_gene_indexed.index.name = None
569+
# Filter and reorder to match the genes actually in the expression matrix
570+
df_gene_filtered = df_gene_indexed.loc[genes_with_expression, :]
571+
572+
# Create AnnData object
573+
adata = ad.AnnData(expression_matrix, obs=obs, var=df_gene_filtered)
574+
575+
# Add resolution and bin info to uns
576+
adata.uns["resolution"] = resolution
577+
adata.uns["bin_name"] = bin_name
578+
579+
# Create table
580+
table = TableModel.parse(
581+
adata,
582+
region=name_points_element,
583+
region_key=SK.REGION_KEY.value,
584+
instance_key=SK.INSTANCE_KEY.value,
585+
)
586+
587+
tables[name_table_element] = table
588+
points[name_points_element] = points_element
589+
590+
# Load pre-computed analysis results if requested
591+
if load_analysis and analysis_dir.exists():
592+
h5ad_files = list(analysis_dir.glob("*.h5ad"))
593+
for h5ad_file in h5ad_files:
594+
# Extract bin size from filename (e.g., B05062E4.bin20_1.0.h5ad)
595+
file_stem = h5ad_file.stem
596+
# Parse bin info from filename
597+
match = re.search(r'\.bin(\d+)_', file_stem)
598+
if match:
599+
bin_size = match.group(1)
600+
table_name = f"analysis_bin{bin_size}"
601+
602+
# Read the h5ad file
603+
adata_analysis = ad.read_h5ad(h5ad_file)
604+
605+
# Check if spatial coordinates exist
606+
if "spatial" in adata_analysis.obsm:
607+
# Add region and instance_key for TableModel
608+
region_name = f"analysis_bin{bin_size}_points"
609+
adata_analysis.obs[SK.REGION_KEY] = region_name
610+
adata_analysis.obs[SK.REGION_KEY] = adata_analysis.obs[SK.REGION_KEY].astype("category")
611+
adata_analysis.obs[SK.INSTANCE_KEY] = adata_analysis.obs.index
612+
613+
# Create table
614+
table_analysis = TableModel.parse(
615+
adata_analysis,
616+
region=region_name,
617+
region_key=SK.REGION_KEY.value,
618+
instance_key=SK.INSTANCE_KEY.value,
619+
)
620+
tables[table_name] = table_analysis
621+
622+
# Create points from spatial coordinates
623+
spatial_coords = adata_analysis.obsm["spatial"]
624+
points_df = pd.DataFrame(
625+
spatial_coords,
626+
columns=[SK.COORD_X, SK.COORD_Y]
627+
)
628+
# Ensure columns are float type (PointsModel validation requires float or int types)
629+
points_df[SK.COORD_X] = points_df[SK.COORD_X].astype(float)
630+
points_df[SK.COORD_Y] = points_df[SK.COORD_Y].astype(float)
631+
points_element = PointsModel.parse(
632+
points_df,
633+
coordinates={"x": SK.COORD_X, "y": SK.COORD_Y},
634+
)
635+
points[region_name] = points_element
636+
637+
tissue_gef.close()
638+
639+
sdata = SpatialData(images=images, tables=tables, points=points)
640+
return sdata

0 commit comments

Comments
 (0)