diff --git a/CHANGELOG.md b/CHANGELOG.md index 03e51af..759fb14 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,8 @@ # Changelog -## Version 0.0.11-0.0.12 +## Version 0.0.11-0.0.13 - BUGFIX: `to_anndata()` only populates `obsm` with spatial coordinates if the original `SpatialExperiment` has spatial coordinates (PR #53, #54) +- Enhance docstring for `to_anndata()` to describe the structure of returned AnnData object (PR #55) ## Version 0.0.10 diff --git a/src/spatialexperiment/spatialexperiment.py b/src/spatialexperiment/spatialexperiment.py index da60c08..48c0be2 100644 --- a/src/spatialexperiment/spatialexperiment.py +++ b/src/spatialexperiment/spatialexperiment.py @@ -1,5 +1,5 @@ from pathlib import Path -from typing import Any, Dict, List, Optional, Sequence, Union +from typing import Any, Dict, List, Optional, Sequence, Union, Tuple from urllib.parse import urlparse from warnings import warn @@ -1019,15 +1019,37 @@ def to_spatial_experiment(): ######>> AnnData interop <<##### ################################ - def to_anndata(self, include_alternative_experiments: bool = False) -> "anndata.AnnData": + def to_anndata( + self, include_alternative_experiments: bool = False + ) -> Tuple["anndata.AnnData", Dict[str, "anndata.AnnData"]]: """Transform :py:class:`~SpatialExperiment`-like into a :py:class:`~anndata.AnnData` representation. + This method converts the main experiment data, spatial coordinates, + and image data into an AnnData structure. Image data, including the + image arrays and their scale factors, are stored within the ``obj.uns["spatial"]`` + dictionary, adhering to a common convention for spatial single-cell data. + + The ``obj.uns["spatial"]`` dictionary is structured as follows: + - It is a dictionary where each key is a unique ``library_id``. + The ``library_id`` is generated by combining ``sample_id`` and ``image_id`` + from the input image data (e.g., "sample1-image01"). + - Each ``library_id`` entry is itself a dictionary containing: + - ``"images"``: A dictionary to store image arrays. + Currently, images are stored under the key ``"hires"`` by default + (e.g., ``obj.uns["spatial"][library_id]["images"]["hires"] = image_numpy_array``). + - ``"scalefactors"``: A dictionary to store scale factors associated + with the images. Currently, scale factors are stored under the key + ``"tissue_hires_scalef"`` by default (e.g., + ``obj.uns["spatial"][library_id]["scalefactors"]["tissue_hires_scalef"] = scale_factor_value``). + + Spatial coordinates are stored in ``obj.obsm["spatial"]``. + Args: include_alternative_experiments: Whether to transform alternative experiments. Returns: - An ``AnnData`` representation of the experiment. + A tuple containing an ``AnnData`` object with spatial information and a list of alternative experiments. """ obj, alt_exps = super().to_anndata(include_alternative_experiments=include_alternative_experiments)