Merge remote-tracking branch 'refs/remotes/origin/eabila'

rendeirolab · Aug 8, 2024 · d0950c4 · d0950c4
2 parents 698ffeb + f21a559
commit d0950c4
Show file tree

Hide file tree

Showing 3 changed files with 209 additions and 46 deletions.
diff --git a/lazyslide/pl/api.py b/lazyslide/pl/api.py
@@ -16,6 +16,44 @@ def tissue(
     render_size=1000,
     ax=None,
 ):
+    """
+    Display the tissue image.
+
+    Parameters
+    ----------
+    wsi : WSI
+        The whole-slide image object.
+    level : int or str, default: "auto"
+        The level to extract the tissue image from.
+    tissue_id : int, default: None
+        The tissue id (piece) to extract.
+    tissue_key : str, default: "tissue"
+        The tissue key.
+    title : str, default: None
+        The title of the plot.
+    show_contours : bool, default: True
+        Show the tissue contours.
+    show_origin : bool, default: True
+        Show the origin.
+    show_id : bool, default: True
+        Show the tissue id.
+    render_size : int, default: 1000
+        The size of the rendered image.
+    ax : matplotlib.axes.Axes, default: None
+        The axes to plot on.
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> import lazyslide as zs
+        >>> wsi = zs.WSI("https://github.com/camicroscope/Distro/raw/master/images/sample.svs")
+        >>> zs.pp.find_tissue(wsi)
+        >>> zs.pl.tissue(wsi)
+
+    """
     if ax is None:
         _, ax = plt.subplots()
     slide = SlideViewer(
@@ -63,6 +101,81 @@ def tiles(
     rasterized=False,
     **kwargs,
 ):
+    """
+    Display the tiles.
+
+    Parameters
+    ----------
+    wsi : WSI
+        The whole-slide image object.
+    feature_key : str, default: None
+        The feature key assigned when generating the numeric tile features.
+    color : str, default: None
+        The column/ feature name that should be visualized from feature_key.
+        If feature_key is None, this is the column name from the tiles table.
+    level : int or str, default: "auto"
+        The level to extract the tissue image from.
+    tissue_id : int, default: None
+        The tissue id (piece) to plot.
+        If None, all will be plotted.
+    tissue_key : str, default: "tissue"
+        The tissue key.
+    tile_key : str, default: "tiles"
+        The tile key.
+    title : str, default: None
+        The title of the plot.
+    show_tissue :  bool, default: True
+        Show the tissue image.
+    show_point : bool, default: True
+        Show the points.
+        By default, the points are black.
+    show_grid : bool, default: False
+        Show the tiles grid.
+    show_contours : bool, default: True
+        Show the tissue contours.
+    show_origin : bool, default: True
+        Show the origin.
+    show_id : bool, default: False
+        Show the tissue (piece) id.
+    render_size : int, default: 1000
+        The size of the rendered image.
+    alpha : float, default: 0.9
+        The transparency of the points.
+    marker : str, default: "o"
+        The marker of the points.
+    vmin : float, default: None
+        The minimum value of the color map.
+    vmax : float, default: None
+        The maximum value of the color map.
+    cmap : str, default: None
+        The color map.
+    norm : matplotlib.colors.Normalize, default: None
+        The normalization of the color map.
+    palette : str, default: None
+        The color palette.
+    size : int, default: 50
+        The size of the points.
+    ax : matplotlib.axes.Axes, default: None
+        The axes to plot on.
+    rasterized : bool, default: False
+        Rasterize the points.
+    kwargs : dict
+        Additional keyword arguments for plotting.
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> import lazyslide as zs
+        >>> wsi = zs.WSI("https://github.com/camicroscope/Distro/raw/master/images/sample.svs")
+        >>> zs.pp.find_tissue(wsi)
+        >>> zs.pp.tiles(wsi, 256, mpp=0.5)
+        >>> zs.pp.tiles_qc(wsi, scorers=["contrast"])
+        >>> zs.pl.tiles(wsi, tissue_id=0, show_grid=True, color='contrast')
+
+    """
     if ax is None:
         _, ax = plt.subplots()
     slide = SlideViewer(

diff --git a/lazyslide/pp/tiles.py b/lazyslide/pp/tiles.py
@@ -32,43 +32,55 @@ def tiles(
     key: str = "tiles",
 ):
     """
-    Generate tiles from the tissue contours
+    Generate tiles within the tissue contours in the WSI.
 
     Parameters
     ----------
     wsi : WSI
-        The whole slide image object
+        The whole slide image object.
     tile_px : int, (int, int)
-        The size of the tile, if tuple, (W, H)
-    stride_px : int, (int, int)
-        The stride of the tile, if tuple, (W, H)
-    edge : bool
-        Whether to include the edge tiles
-    mpp : float
-        The requested mpp of the tiles, if None, use the slide mpp
-    slide_mpp : float
-        This value will override the slide mpp
-    tolerance : float
-        The tolerance when matching the mpp
-    background_fraction : float
+        The size of the tile, if tuple, (W, H).
+    stride_px : int, (int, int), default None
+        The stride of the tile, if tuple, (W, H).
+    edge : bool, default False
+        Whether to include the edge tiles.
+    mpp : float, default None
+        The requested mpp of the tiles, if None, use the slide mpp.
+    slide_mpp : float, default None
+        This value will override the slide mpp.
+    tolerance : float, default 0.05
+        The tolerance when matching the mpp.
+    background_fraction : float, default 0.3
         For flavor='mask',
-        The fraction of background in the tile, if more than this, discard the tile
+        The fraction of background in the tile, if more than this, discard the tile.
     min_pts : int
         For flavor='polygon-test',
-        The minimum number of points of a rectangle tile that should be inside the tissue
-        should be within [0, 4]
+        The minimum number of points of a rectangle tile that should be inside the tissue.
+        Should be within [0, 4].
     flavor : str, {'polygon-test', 'mask'}
-        The flavor of the tile generation, either 'polygon-test' or 'mask'
-        - 'polygon-test': Use point polygon test to check if the tiles points are inside the contours
-        - 'mask': Transform the contours and holes into binary mask and check the fraction of background
-    filter : Callable
-        A callable that takes in a image and return a boolean value
-    errors : str
-        The error handling strategy, either 'raise' or 'warn'
+        The flavor of the tile generation, either 'polygon-test' or 'mask':
+        - 'polygon-test': Use point polygon test to check if the tiles points are inside the contours.
+        - 'mask': Transform the contours and holes into binary mask and check the fraction of background.
+    filter : Callable, default None
+        A callable that takes in a image and return a boolean value.
+    errors : str, default 'raise'
+        The error handling strategy, either 'raise' or 'warn'.
     tissue_key : str, default 'tissue'
-        The key of the tissue contours
+        The key of the tissue contours.
     key : str, default 'tiles'
-        The key of the tiles
+        The key of the tiles.
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> import lazyslide as zs
+        >>> wsi = zs.WSI("https://github.com/camicroscope/Distro/raw/master/images/sample.svs")
+        >>> zs.pp.find_tissue(wsi)
+        >>> zs.pp.tiles(wsi, 256, mpp=0.5)
+        >>> zs.pl.tiles(wsi, tissue_id=0, show_grid=True, show_point=False)
 
     """
     # Check if tissue contours are present
@@ -276,25 +288,36 @@ def tiles_qc(
     key_added: str = "qc",
 ):
     """
-    Score the tiles and filter the tiles based on the score
+    Score the tiles and filter the tiles based on their quality scores.
 
     Parameters
     ----------
     wsi : WSI
-        The whole slide image object
+        The whole slide image object.
     scorers : ScorerBase
-        The scorer object or a callable that takes in a image and return a score
-        You can also pass in a string
+        The scorer object or a callable that takes in an image and returns a score.
+        You can also pass in a string:
         - 'focus': A FocusLite scorer that will score the focus of the image
         - 'contrast': A Contrast scorer that will score the contrast of the image
     num_workers : int, default: 1
-        The number of workers to use
+        The number of workers to use.
     pbar : bool, default: True
-        Whether to show the progress bar
+        Whether to show the progress bar or not.
     key : str
-        The key of the tiles
+        The key of the tiles.
     key_added : str
-        The key of the filtered tiles
+        The key of the filtered tiles.
+
+    Examples
+    --------
+    .. code-block:: python
+
+        >>> import lazyslide as zs
+        >>> wsi = zs.WSI("https://github.com/camicroscope/Distro/raw/master/images/sample.svs")
+        >>> zs.pp.find_tissue(wsi)
+        >>> zs.pp.tiles(wsi, 256, mpp=0.5)
+        >>> zs.pp.tiles_qc(wsi, scorers=["contrast"])
+        >>> wsi.get_tiles_table('tiles').head(n=2)
 
     """
     from lazyslide.cv.scorer import FocusLite, Contrast
@@ -388,25 +411,25 @@ def _chunk_scoring(tiles, spec, reader, scorer, queue):
 @njit
 def create_tiles(image_shape, tile_w, tile_h, stride_w=None, stride_h=None, edge=True):
     """Create the tiles, return coordination that comprise the tiles
-        and the index of points for each rect
+        and the index of points for each rectangular.
 
     Parameters
     ----------
     image_shape : (int, int)
-        The (H, W) of the image
+        The (H, W) of the image.
     tile_w, tile_h: int
-        The width/height of tile
-    stride_w, stride_h : int
-        The width/height of stride when move to next tile
-    edge : bool
-        Whether to include the edge tiles
+        The width/height of tiles.
+    stride_w, stride_h : int, default None
+        The width/height of stride when moving to the next tile.
+    edge : bool, default True
+        Whether to include the edge tiles.
 
     Returns
     -------
     coordinates : np.ndarray (N, 2)
-        The coordinates of the tiles, N is the number of tiles
+        The coordinates of the tiles, N is the number of tiles.
     indices : np.ndarray (M, 4)
-        The indices of the points for each rect, M is the number of rects
+        The indices of the points for each rect, M is the number of rects.
 
     """
     height, width = image_shape
@@ -449,7 +472,7 @@ def create_tiles(image_shape, tile_w, tile_h, stride_w=None, stride_h=None, edge
 
 @njit
 def filter_tiles(mask, tiles_coords, tile_w, tile_h, filter_bg=0.8):
-    """Return a binary array that indicate which tile should be left
+    """Returns a binary array that indicate which tile should be left.
 
     Parameters
     ----------

diff --git a/lazyslide/pp/tissue_segment.py b/lazyslide/pp/tissue_segment.py
@@ -33,8 +33,35 @@ def find_tissue(
     ----------
     wsi : WSI
         Whole-slide image object.
-    level : int, optional
-        The level to use for segmentation, by default None.
+    level : int, optional, default: None
+        The level to use for segmentation.
+    use_saturation : bool, optional, default: False
+        Use saturation channel for segmentation.
+    blur_ksize : int, optional, default: 17
+    threshold : int, optional, default: 7
+    morph_n_iter : int, optional, default: 3
+    morph_k_size : int, optional, default: 7
+    min_tissue_area : float, optional, default: 1e-3
+        The minimum area of tissue.
+    min_hole_area : float, optional, default: 1e-5
+        The minimum area of holes.
+    detect_holes : bool, optional, default: True
+        Detect holes in tissue regions.
+    filter_artifacts : bool, optional, default: True
+        Filter artifacts out.
+    key : str, optional, default: "tissue"
+        The key to store the tissue contours.
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> import lazyslide as zs
+        >>> wsi = zs.WSI("https://github.com/camicroscope/Distro/raw/master/images/sample.svs")
+        >>> zs.pp.find_tissue(wsi)
+        >>> zs.pl.tissue(wsi)
 
     """
     # Get optimal level for segmentation