Add details to to_anndata() docstring (#55)

Author: keviny2

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

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)