spateo.digitization.contour
===========================

.. py:module:: spateo.digitization.contour

.. autoapi-nested-parse::

   Written by @Jinerhal, adapted by @Xiaojieqiu.



Functions
---------

.. autoapisummary::

   spateo.digitization.contour.gen_cluster_image
   spateo.digitization.contour.extract_cluster_contours
   spateo.digitization.contour.set_domains


Module Contents
---------------

.. py:function:: gen_cluster_image(adata: anndata.AnnData, bin_size: Optional[int] = None, spatial_key: str = 'spatial', cluster_key: str = 'scc', label_mapping_key: str = 'cluster_img_label', cmap: str = 'tab20', show: bool = True) -> numpy.ndarray

   Generate matrix/image of spatial clusters with distinct labels/colors.

   :param adata: The adata object used to create the matrix/image for clusters.
   :param bin_size: The size of the binning.
   :param spatial_key: The key name of the spatial coordinates in `adata.obs`
   :param cluster_key: The key name of the spatial cluster in `adata.obs`
   :param label_mapping_key: The key name to store the label index values, mapped from the cluster names in `adata.obs`.
                             Note that background is 0 so `label_mapping_key` starts from 1.
   :param cmap: The colormap that will be used to draw colors for the resultant cluster image.
   :param show: Whether to visualize the cluster image.

   :returns:

             A numpy array that stores the image of clusters, each with a distinct color. When `show`
                 is True, `plt.imshow(cluster_rgb_image)` will be used to plot the clusters each with distinct labels
                 prepared from the designated cmap.
   :rtype: cluster_label_image


.. py:function:: extract_cluster_contours(cluster_label_image: numpy.ndarray, cluster_labels: Union[int, List], bin_size: int, k_size: float = 2, min_area: float = 9, close_kernel: int = cv2.MORPH_ELLIPSE, show: bool = True) -> Tuple[Tuple, numpy.ndarray, numpy.ndarray]

   Extract contour(s) for area(s) formed by buckets of the same spatial cluster.

   :param cluster_label_image: the image that sets the pixels of the cluster of interests as the front color (background
                               is 0).
   :param cluster_labels: The label value(s) of clusters of interests.
   :param bin_size: The size of the binning.
   :param k_size: Kernel size of the elliptic structuring element.
   :param min_area: Minimal area threshold corresponding to the resulting contour(s).
   :param close_kernel: The value to indicate the structuring element. By default, we use a circular structuring element.
   :param show: Visualize the result.

   :returns: The Tuple coordinates of contours identified.
             cluster_image_close: The resultant image of the area of interest with small area removed.
             cluster_image_contour: The resultant image of the contour, generated from `cluster_image_close`.
   :rtype: contours


.. py:function:: set_domains(adata_high_res: anndata.AnnData, adata_low_res: Optional[anndata.AnnData] = None, spatial_key: str = 'spatial', cluster_key: str = 'scc', domain_key_prefix: str = 'domain', bin_size_high: Optional[int] = None, bin_size_low: Optional[int] = None, k_size: float = 2, min_area: float = 9) -> None

   Set the domains for each bucket based on spatial clusters. Use adata object of low resolution for contour
       identification but adata object of high resolution  for domain assignment.

   :param adata_high_res: The anndata object in high spatial resolution. The adata with smaller binning (or single cell
                          segmetnation) is more suitable to define more fine grained spatial domains.
   :param adata_low_res: The anndata object in low spatial resolution. When using data with big binning, it can often
                         produce better spatial domain clustering results with the `scc` method and thus domain/domain contour
                         identification.
   :param spatial_key: The key in `.obsm` of the spatial coordinate for each bucket. Should be same key in both
                       `adata_high_res` and `adata_low_res`.
   :param cluster_key: The key in `.obs` (`adata_low_res`) to the spatial cluster.
   :param domain_key_prefix: The key prefix in `.obs` (in `adata_high_res`) that will be used to store the spatial domain
                             for each bucket. The full key name will be set as: `domain_key_prefix` + "_" + `cluster_key`.
   :param bin_size_low: The binning size of the `adata_high_res` object.
   :param bin_size_low: The binning size of the `adata_low_res` object (only works when `adata_low_res` is provided).
   :param k_size: Kernel size of the elliptic structuring element.
   :param min_area: Minimal area threshold corresponding to the resulting contour(s).

   :returns: Nothing but update the `adata_high_res` with the `domain` in `domain_key_prefix` + "_" + `cluster_key`.