Expose naming space of accessors

Author: Mr-Milk

pyproject.toml

@@ -13,8 +13,8 @@ requires-python = ">=3.10"
 dynamic = ["version", "description"]
 
 dependencies = [
-    "spatialdata>=0.2.7rc0",
-    "opencv-python",
+    "spatialdata>=0.3.0",
+    "opencv-python-headless",
     "openslide-python",
     "openslide-bin",
     "tiffslide",

wsidata/__init__.py

@@ -5,7 +5,7 @@
 import wsidata.dataset as dataset
 from ._model import WSIData, TileSpec
 from .io import open_wsi, agg_wsi
-from ._accessors import (
+from .accessors import (
     register_wsidata_accessor,
     FetchAccessor,
     IterAccessor,

wsidata/_model/core.py

@@ -15,7 +15,7 @@
 from spatialdata import SpatialData
 from spatialdata.models import SpatialElement
 
-from .._accessors import FetchAccessor, IterAccessor, DatasetAccessor
+from ..accessors import FetchAccessor, IterAccessor, DatasetAccessor
 from .._utils import find_stack_level
 from ..reader import ReaderBase, SlideProperties
 
@@ -26,99 +26,80 @@ class WSIData(SpatialData):
     and a whole slide image reader.
 
     .. note::
-     Use the :func:`open_wsi` function to create a WSIData object.
+       Use the :func:`open_wsi` function to create a WSIData object.
 
     By default, the whole slide image is not attached to the SpatialData.
     A thumbnail version of the whole slide image is attached for visualization purpose.
 
-    The WSIData contains four main components:
-
     .. list-table::
-     :header-rows: 1
-
-     * -
-       - Whole slide image
-       - Tissue contours
-       - Tile locations
-       - Features
-
-     * - **SpatialData Slot**
-       - :bdg-danger:`images`
-       - :bdg-danger:`shapes`
-       - :bdg-danger:`shapes`
-       - :bdg-danger:`tables`
-
-     * - **Default Key**
-       - :bdg-info:`wsi_thumbnail`
-       - :bdg-info:`tissues`
-       - :bdg-info:`tiles`
-       - :bdg-info:`\{feature_key\}_\{tile_key\}`
-
-     * - | **Attributes**
-         | **Slot**
-         | **Key**
-       - | :class:`SlideProperties <wsidata.reader.SlideProperties>`
-         | :bdg-danger:`tables`
-         | :bdg-info:`slide_properties`
-       -
-       - | :class:`TileSpec <wsidata.TileSpec>`
-         | :bdg-danger:`tables`
-         | :bdg-info:`tile_spec`
-       -
-
-     * - **Content**
-       - | :class:`DataArray <xarray.DataArray>`
-         | (c, y, x) format.
-       - | :class:`GeoDataFrame <geopandas.GeoDataFrame>` with columns:
-         | :bdg-black:`tissue_id`
-         | :bdg-black:`geometry`
-       - | :class:`GeoDataFrame <geopandas.GeoDataFrame>` with columns:
-         | :bdg-black:`tile_id`
-         | :bdg-black:`x`, :bdg-black:`y`
-         | :bdg-black:`tissue_id`
-         | :bdg-black:`geometry`
-       - | :class:`AnnData <anndata.AnnData>` with:
-         | :code:`X`: The feature matrix
-         | :code:`varm`: :bdg-black:`agg_slide`, :bdg-black:`agg_tissue`
-
-
-
-     You can interact with WSIData using the following accessors:
-
-     - :class:`get <wsidata.GetAccessor>`: Access data from the WSIData object.
-     - :class:`iter <wsidata.IterAccessor>`: Iterate over data in the WSIData object.
-     - :class:`ds <wsidata.DatasetAccessor>`: Create deep learning datasets from the WSIData object.
-     - To implement your own accessors, use :func:`register_wsidata_accessor <wsidata.register_wsidata_accessor>`.
-
-     For analysis purpose, you can override two slide properties:
-
-     - microns per pixel (mpp): Using the :meth:`set_mpp` method.
-     - bounds: Using the :meth:`set_bounds` method.
-
-     Parameters
-     ----------
-     reader : :class:`ReaderBase <wsidata.reader.ReaderBase>`
-         A reader object that can interface with the whole slide image file.
-     sdata : :class:`SpatialData <spatialdata.SpatialData>`
-         A SpatialData object for storing analysis data.
-     backed_file : str or Path
-         Storage location to the SpatialData object.
-     slide_properties_source : {'slide', 'sdata'}, default: 'sdata'
-         The source of the slide properties.
-
-         - "slide": load from the reader object.
-         - "sdata": load from the SpatialData object.
-
-     Attributes
-     ----------
-     properties : :class:`SlideProperties <wsidata.reader.SlideProperties>`
-         The properties of the whole slide image.
-     reader : :class:`ReaderBase <wsidata.reader.ReaderBase>`
-         The reader object for interfacing with the whole slide image.
-     sdata : :class:`SpatialData <spatialdata.SpatialData>`
-         The SpatialData object containing the spatial data.
-     backed_file : Path
-         The path to the backed file.
+       :header-rows: 1
+
+       * - **Content**
+         - **Default key**
+         - **Slot**
+         - **Type**
+
+       * - Whole slide image
+         - :bdg-info:`wsi_thumbnail`
+         - :bdg-danger:`images`
+         - :class:`DataArray <xarray.DataArray>` (c, y, x) format
+
+       * - Slide Properties
+         - :bdg-info:`slide_properties`
+         - :bdg-danger:`attrs`
+         - :class:`SlideProperties <wsidata.reader.SlideProperties>`
+
+       * - Tissue contours
+         - :bdg-info:`tissues`
+         - :bdg-danger:`shapes`
+         - :class:`GeoDataFrame <geopandas.GeoDataFrame>`
+
+       * - Tile locations
+         - :bdg-info:`tiles`
+         - :bdg-danger:`shapes`
+         - :class:`GeoDataFrame <geopandas.GeoDataFrame>`
+
+       * - Tile specifications
+         - :bdg-info:`tile_spec`
+         - :bdg-danger:`attrs`
+         - :class:`TileSpec <wsidata.TileSpec>`
+
+       * - Features
+         - :bdg-info:`{feature_key}_{tile_key}`
+         - :bdg-danger:`tables`
+         - :class:`AnnData <anndata.AnnData>`
+
+
+    You can interact with WSIData using the following accessors:
+
+    - :class:`fetch <wsidata.FetchAccessor>`: Access data from the WSIData object.
+    - :class:`iter <wsidata.IterAccessor>`: Iterate over data in the WSIData object.
+    - :class:`ds <wsidata.DatasetAccessor>`: Create deep learning datasets from the WSIData object.
+    - To implement your own accessors, use :func:`register_wsidata_accessor <wsidata.register_wsidata_accessor>`.
+
+    For analysis purpose, you can override two slide properties:
+
+    - **microns per pixel (mpp)**: Using the :meth:`set_mpp` method.
+    - **bounds**: Using the :meth:`set_bounds` method.
+
+    Other Parameters
+    ----------------
+    reader : :class:`ReaderBase <wsidata.reader.ReaderBase>`
+        A reader object that can interface with the whole slide image file.
+    slide_properties_source : {'slide', 'sdata'}, default: 'sdata'
+        The source of the slide properties.
+
+        - "slide": load from the reader object.
+        - "sdata": load from the SpatialData object.
+
+    Attributes
+    ----------
+    properties : :class:`SlideProperties <wsidata.reader.SlideProperties>`
+        The properties of the whole slide image.
+    reader : :class:`ReaderBase <wsidata.reader.ReaderBase>`
+        The reader object for interfacing with the whole slide image.
+    wsi_store :
+        The store path for the whole slide image.
 
     """
 
@@ -186,9 +167,11 @@ def __repr__(self):
         )
 
     def set_exclude_elements(self, elements):
+        """Set the elements to be excluded from serialize to the WSIData object on disk."""
         self._exclude_elements.update(elements)
 
     def set_wsi_store(self, store: str | Path):
+        """Set the on disk path for the WSIData."""
         self._wsi_store = Path(store)
 
     def _gen_elements(
@@ -379,10 +362,17 @@ def ds(self):
 class TileSpec:
     """Data class for storing tile specifications.
 
-    # There are 3 levels of tile size that we should record:
-    # 1. The destined tile size requested by the user
-    # 2. The tile size used by the image reader to optimize the performance
-    # 3. The actual tile size at the level 0
+    To enable efficient tils generation, there are 3 levels of tile size:
+
+    1. The destined tile size and level requested by the user
+    2. The tile size and level used by the image reader to optimize the performance
+    3. The actual tile size at the level 0
+
+    This enables user to request tile size and level that are not exist in the image pyramids.
+    For example, if our slide is mpp=0.5 (20X) with pyramids of mpp=[0.5, 2.0, 4.0],
+    and user request mpp=1.0 (10X) with tile size 512x512. There is no direct level to read from,
+    we need to read from mpp=0.5 with tile size of 1024x1024 and downsample to 512x512.
+
 
     Parameters
     ----------
@@ -404,7 +394,7 @@ class TileSpec:
     tissue_name : str, optional
         The name of the tissue.
 
-    Properties
+    Attributes
     ----------
     ops_{height, width} : int
         The height/width of the tile when retrieving images.

wsidata/_accessors/__init__.py wsidata/accessors/__init__.py

@@ -61,10 +61,21 @@ def _normalize_polygon(polygon, bbox):
 
 
 class TissueContour:
-    tissue_id: int
-    shape: Polygon
-    as_array: bool
-    dtype: np.dtype
+    """The data container return by :meth:`wsidata.iter.tissue_contours <wsidata.IterAccessor.tissue_contours>`
+
+    Attributes
+    ----------
+    tissue_id : int
+        The id of tissue
+    contour : :class:`Polygon <shapely.Polygon>` or :class:`np.ndarray <numpy.ndarray>`
+        The contour of the tissue
+    holes : array of :class:`Polygon <shapely.Polygon>` or :class:`np.ndarray <numpy.ndarray>`
+        The holes of the tissue
+    as_array : bool
+        Whether to return the result as array or polygon, can be set to True or False.
+
+
+    """
 
     def __init__(self, tissue_id, shape, as_array=False, dtype=None):
         self.tissue_id = tissue_id
@@ -76,18 +87,23 @@ def __init__(self, tissue_id, shape, as_array=False, dtype=None):
     def as_array(self):
         return self._as_array
 
+    @as_array.setter
+    def as_array(self, v):
+        self._as_array = v
+
     @property
     def dtype(self):
         return self._dtype
 
-    @cached_property
+    @property
     def contour(self) -> np.ndarray | Polygon:
+        """The contour of the tissue"""
         if self.as_array:
             return np.array(self.shape.exterior.coords, dtype=self.dtype)
         else:
             return Polygon(self.shape.exterior.coords)
 
-    @cached_property
+    @property
     def holes(self) -> List[np.ndarray | Polygon]:
         if self.as_array:
             return [
@@ -161,10 +177,6 @@ def plot(
 
 
 class TissueImage(TissueContour):
-    image: np.ndarray
-    format: str
-    mask_bg: int | None
-
     def __init__(
         self,
         tissue_id,
@@ -329,7 +341,7 @@ def __repr__(self):
             f"TileImage(id={self.id}, x={self.x}, y={self.y}, "
             f"tissue_id={self.tissue_id}) {shapes_repr} "
             f"with attributes: \n"
-            f"image, annot_mask, annot_shapes"
+            f"image, has_annot, annot_mask, annot_shapes, normed_annot_shapes, annot_labels, tissue_id, x, y"
         )
 
     def plot(
@@ -353,10 +365,11 @@ def plot(
         ax.imshow(self.image, **kwargs)
 
         # Create palette
-        if palette is None:
-            palette = {k: v for k, v in zip(self.annot_labels.keys(), PALETTE)}
+        if self.has_annot:
+            if palette is None:
+                palette = {k: v for k, v in zip(self.annot_labels.keys(), PALETTE)}
 
-        if show_annots and self.annot_shapes is not None:
+        if show_annots and self.has_annot:
             for shape, name, label in self.annot_shapes:
                 path = Path.make_compound_path(
                     Path(np.asarray(shape.exterior.coords)[:, :2]),
@@ -379,7 +392,7 @@ def plot(
                     alpha=alpha,
                 )
                 ax.add_patch(fill)
-        if legend:
+        if legend and self.has_annot:
             from legendkit import cat_legend
 
             cat_legend(
@@ -395,7 +408,11 @@ def plot(
 class IterAccessor(object):
     """An accessor to iterate over the WSI data.
 
-    Usage: `wsidata.iter`
+    Usage: :code:`wsidata.iter`
+
+    The iter accessor will return a data container,
+    you can access the data within container using attributes.
+    All container has :code:`.plot()` method to visualize its content.
 
     """
 
@@ -427,12 +444,10 @@ def tissue_contours(
 
         Returns
         -------
-        TissueContour
-            A named tuple with fields:
+        :class:`TissueContour <wsi.accessors.iter.TissueContour>`
 
-            - tissue_id : The tissue id.
-            - contour : The tissue contour as a shapely geometry or an array.
-            - holes : The holes in the tissue contour.
+        - tissue_id : The tissue id.
+        - shape : :class:`Polygon <shapely.Polygon>` or :class:`np.ndarray <numpy.ndarray>` The tissue shape as a shapely geometry or an array.
 
         """
 
@@ -486,14 +501,13 @@ def tissue_images(
 
         Returns
         -------
-        TissueImage
-            A named tuple with fields:
+        :class:`TissueImage <wsi.accessors.iter.TissueImage>`
 
-            - tissue_id : The tissue id.
-            - x : The x-coordinate of the image.
-            - y : The y-coordinate of the image.
-            - image : The tissue image.
-            - mask : The tissue mask.
+        - tissue_id : The tissue id.
+        - x : The x-coordinate of the image.
+        - y : The y-coordinate of the image.
+        - image : The tissue image.
+        - mask : The tissue mask.
 
         """
         import cv2

wsidata/_accessors/dataset.py wsidata/accessors/dataset.py

@@ -54,7 +54,7 @@ def decorator(accessor):
                 stacklevel=find_stack_level(),
             )
         setattr(cls, name, CachedAccessor(name, accessor))
-        # cls._accessors.add(name)
+        # cls.accessors.add(name)
         return accessor
 
     return decorator