|
25 | 25 | if TYPE_CHECKING: |
26 | 26 | from collections.abc import Mapping |
27 | 27 |
|
28 | | -__all__ = ["stereoseq"] |
| 28 | +__all__ = ["stereoseq", "stereoseq_v8"] |
29 | 29 |
|
30 | 30 |
|
31 | 31 | @inject_docs(xx=SK) |
@@ -340,3 +340,301 @@ def stereoseq( |
340 | 340 |
|
341 | 341 | sdata = SpatialData(images=images, tables=tables, shapes=shapes, points=points) |
342 | 342 | 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