API Reference

SubDomain

Analyse domains based on labels in a 2D grid.

Parameters:

Name	Type	Description	Default
label_map	ndarray | Array	An integer array where all positive values correspond to a specific label and negative values are background.	required
label_name	str	Name of the labels.	'label'
labels	Iterable[str] | None	Names corresponding to each label in label_map.	None

Raises:

Type	Description
ValueError	If the length of labels does not match the number of labels in label_map.

Attributes:

Name	Type	Description
SubDomain.label_map	ndarray | Array	2D labeled grid.
SubDomain.n_labels	int	Number of different categories in label_map (excluding background).
SubDomain.label_name	str	Name of the labels.
SubDomain.labels	str	Names corresponding to each label in label_map.
SubDomain.neighborhoods	Array	The consolidated neighborhoods after binning.
SubDomain.binsize	int	Size of each domain bin.
SubDomain.domains	ndarray	The assigned domain for each bin.
SubDomain.n_domains	int	Number of domains.

Source code in subdomain/_domaindetection.py

class SubDomain:
    """Analyse domains based on labels in a 2D grid.

    Parameters
    ----------
    label_map : numpy.ndarray | jax.Array
        An integer array where all positive values correspond to a specific label
        and negative values are background.
    label_name : str, optional
        Name of the labels.
    labels : collections.abc.Iterable[str] | None, optional
        Names corresponding to each label in `label_map`.

    Raises
    ------
    ValueError
        If the length of `labels` does not match the number of labels in `label_map`.

    Attributes
    ----------
    SubDomain.label_map : numpy.ndarray | jax.Array
        2D labeled grid.
    SubDomain.n_labels : int
        Number of different categories in `label_map` (excluding background).
    SubDomain.label_name : str
        Name of the labels.
    SubDomain.labels : str
        Names corresponding to each label in `label_map`.
    SubDomain.neighborhoods : jax.Array
        The consolidated neighborhoods after binning.
    SubDomain.binsize : int
        Size of each domain bin.
    SubDomain.domains : numpy.ndarray
        The assigned domain for each bin.
    SubDomain.n_domains : int
        Number of domains.
    """

    def __init__(
        self,
        label_map: np.ndarray | jax.Array,
        /,
        *,
        label_name: str = "label",
        labels: Iterable[str] | None = None,
    ):
        # TODO validate the unique indices
        n_labels = int(label_map.max()) + 1

        if labels is not None:
            labels = list(labels)
            if len(labels) != n_labels:
                raise ValueError(
                    "Length of `labels` must match the number of labels in `label_map`."
                )

        self.labels = labels
        self.label_map = label_map
        self.n_labels = n_labels
        self.label_name = label_name

    def calculate_neighborhoods(
        self,
        binsize: int,
        radius: int,
        *,
        neighborhood: str = "circle",
        normalize: bool = True,
        sigma: float = 1.0,
    ):
        """Calculate the neighborhoods.

        The label map is binned and subsequently the neighborhood in terms of frequency
        per label calculated for each bin.

        Parameters
        ----------
        binsize : int
            Size to bin the labeled grid by.
        radius : int
            Radius for the neighborhood aggregation. The size of the neighborhood will be
            `2 * binsize * (radius + 1)`
        neighborhood : str, optional
            Method for defining the neighborhood shape. Options:
                - "circle": A circular neighborhood based on Euclidean distance.
                - "square": A square neighborhood with all elements in the kernel.
                - "gaussian": A Gaussian-weighted neighborhood.
        normalize : bool, optional
            Whether to normalize the neighborhood of each bin (L1-norm).
        sigma : float, optional
            Standard deviation for the Gaussian kernel, if `neighborhood` is 'gaussian'.
        """

        match neighborhood:
            case "gaussian":
                neighborhood_fn = partial(_gaussian_neighborhood, sigma=sigma)

            case "square":
                neighborhood_fn = _square_neighborhood

            case "circle":
                neighborhood_fn = _circle_neighborhood

            case _:
                raise ValueError(
                    f"Unknown `neighborhood`: {neighborhood}. "
                    f"Supported types are: {sorted(_VALID_NEIGHH)}"
                )

        # TODO improve by allocating first?
        mtx = jnp.dstack(
            [
                neighborhood_fn(_bin_array(self.label_map == i, binsize), radius)
                for i in range(self.n_labels)
            ]
        )

        if normalize:
            l1_norm = mtx.sum(axis=2)
            # Avoid division by zero
            mtx /= l1_norm.at[l1_norm == 0].set(1e-10)[:, :, None]
            # set to nan
            mtx = mtx.at[l1_norm == 0, :].set(jnp.nan)
        self.neighborhoods = mtx
        self.binsize = binsize

    # GMMs cluster on GPU and CPU was added by Jing Chen
    def cluster_neighborhoods(
        self,
        n_clusters: int,
        method: str = "kmeans",
        *,
        gpu: bool = False,
        random_state: int = 1,
        **kwargs,
    ):
        """Cluster the aggregated neighborhoods.

        Assigns a domain (cluster) to each bin in the calculated neighborhoods (requires
        to first run [subdomain.SubDomain.calculate_neighborhoods][]).

        Parameters
        ----------
        n_clusters : int
            Number of clusters.
        method : str, optional
            TODO
        gpu : bool, optional
            Whether to use the GPU for KMeans clustering.
        random_state : int, optional
            Random state for reproducibility.
        kwargs
            Other keyword arguments will be passed to [sklearn.cluster.KMeans][], [cuml.cluster.KMeans][],
            [sklearn.mixture.GaussianMixture][], or [torchgmm.bayes.GaussianMixture][] depending on
            the `method` and `gpu` parameters.
        """
        torch_tensor = False
        match method:
            case "kmeans":
                if gpu:
                    import cuml

                    model = cuml.cluster.KMeans(
                        n_clusters=n_clusters,
                        random_state=random_state,
                        output_type="numpy",
                        **kwargs,
                    )
                else:
                    model = KMeans(
                        n_clusters=n_clusters, random_state=random_state, **kwargs
                    )
            case "gmm":
                if gpu:
                    import torch
                    from torchgmm.bayes import GaussianMixture as TorchGaussianMixture

                    # TODO: how to seed
                    torch_tensor = True
                    model = TorchGaussianMixture(num_components=n_clusters, **kwargs)
                else:
                    model = GaussianMixture(
                        n_components=n_clusters, random_state=random_state, **kwargs
                    )
            case _:
                raise ValueError(
                    f"Unknown `method`: {method}. "
                    f"Supported types are: {sorted(_VALID_CLUSTER)}"
                )

        mtx_flat = _flatten_2d(self.neighborhoods)
        not_nan = ~jnp.isnan(mtx_flat).any(axis=1)

        domain = np.full(mtx_flat.shape[0], -1, dtype=np.int16)
        if torch_tensor:
            # TODO is this needed?
            prediction = model.fit_predict(
                torch.tensor(mtx_flat[not_nan], dtype=torch.float32).cuda()
            ).numpy(force=True)
        else:
            prediction = model.fit_predict(mtx_flat[not_nan])
        domain[not_nan] = prediction
        self.domains = domain.reshape(self.neighborhoods.shape[:2])
        self.n_domains = n_clusters

    def identify_domains(
        self,
        n_clusters: int,
        binsize: int = 8,
        radius: int = 10,
        *,
        neighborhood: str = "circle",
        normalize: bool = True,
        sigma: float = 1.0,
        clustering_method: str = "kmeans",
        gpu: bool = False,
        random_state: int = 1,
        **kwargs,
    ):
        """Identify domains from labeled grid.

        This is a wrapper around [subdomain.SubDomain.calculate_neighborhoods][] and
        [subdomain.SubDomain.cluster_neighborhoods][].

        If the neighborhood has already been calculated (and the parameters do not need
        to be changed) it is more efficient to just cluster the domains rather than
        recalculating the neighborhoods.

        Parameters
        ----------
        n_clusters : int
            Number of domains (clusters) to identify.
        binsize : int
            Size to bin the labeled grid by.
        radius : int
            Radius for the neighborhood aggregation. The size of the neighborhood will be
            `2 * binsize * (radius + 1)`
        neighborhood : str, optional
            Method for defining the neighborhood shape. Options:
            - 'circle': A circular neighborhood based on Euclidean distance.
            - 'square': A square neighborhood with all elements in the kernel.
            - 'gaussian': A Gaussian-weighted neighborhood.
        normalize : bool, optional
            Whether to normalize the neighborhood of each bin (L1-norm).
        sigma : float, optional
            TODO
        clustering_method : str, optional
            The clustering method to use. Options are:
            - 'kmeans': Use KMeans clustering.
            - 'gmm': Use Gaussian Mixture Model clustering.
        gpu: bool, optional
            Whether to use the GPU for KMeans clustering. The neighborhood aggregation will
            run by default on GPU if available.
        random_state : int, optional
            Random state for reproducibility.
        kwargs
            Other keyword arguments will be passed to the clustering method.
            See [subdomain.SubDomain.cluster_neighborhoods][] for details.
        """
        if neighborhood not in _VALID_NEIGHH:
            raise ValueError(
                f"Unknown `neighborhood`: {neighborhood}. "
                f"Supported types are: {sorted(_VALID_NEIGHH)}"
            )
        if clustering_method not in _VALID_CLUSTER:
            raise ValueError(
                f"Unknown `clustering_method`: {clustering_method}. "
                f"Supported types are: {sorted(_VALID_CLUSTER)}"
            )

        self.calculate_neighborhoods(
            binsize, radius, neighborhood=neighborhood, normalize=normalize, sigma=sigma
        )
        self.cluster_neighborhoods(
            n_clusters, clustering_method, gpu=gpu, random_state=random_state, **kwargs
        )

    def domain_neighborhoods(self) -> pd.DataFrame:
        """Average neighborhood of the domains.

        Returns
        -------
        pandas.DataFrame
            Average neighborhood.
        """
        neighbor_fractions = (
            pd.DataFrame(_flatten_2d(self.neighborhoods), columns=self.labels)
            .assign(domain=self.domains.ravel())
            .loc[lambda df: df["domain"].ge(0)]
            .groupby("domain")
            .agg("mean")
        )
        neighbor_fractions.columns.name = self.label_name
        return neighbor_fractions

    def domain_composition(self) -> pd.DataFrame:
        """Label composition of each domain.

        Returns
        -------
        pandas.DataFrame
            Label composition.
        """
        name = self.label_name

        domain_composition = (
            pd.DataFrame(
                {
                    name: self.label_map.ravel(),
                    "domain": self.rescale_domain_map().ravel(),
                }
            )
            .loc[lambda df: df[name].ge(0)]
            .groupby(["domain", name])
            .size()
        )
        domain_composition /= domain_composition.groupby("domain").transform("sum")
        return (
            domain_composition.to_frame("fraction")
            .reset_index()
            .pivot(index="domain", columns=name, values="fraction")
            .fillna(0)
        )

    def rescale_domain_map(self) -> np.ndarray:
        """Rescale domain map to original labeled grid size, i.e., prior to binning."""
        rescaled_domains = np.repeat(
            np.repeat(self.domains, self.binsize, axis=0), self.binsize, axis=1
        )[: self.label_map.shape[0], : self.label_map.shape[1]]
        return rescaled_domains

    def plot_domains(
        self,
        domain_palette=cc.glasbey_dark,
        label_palette=cc.glasbey_light,
        *,
        scale: tuple[float, str] | None = None,
        **kwargs,
    ) -> Figure:
        """Spatial plot of domains and labeled grid.

        Parameters
        ----------
        domain_palette
            Palette to use for the domain plot. Must be a valid argument for
            [seaborn.color_palette][]
        label_palette
            Palette to use for the labeled grid plot. Must be a valid argument for
            [seaborn.color_palette][]
        scale : tuple[float, str] | None
            Size of a pixel in the original labeled grid as a tuple of the value and
            the unit (must be one of nm, um, ...) e.g. `(5, 'um')`.
        kwargs
            Other keyword arguments are passed to `matplotlib-scalebar.ScaleBar`

        Returns
        -------
        matplotlib.figure.Figure
        """

        def _color_lut(
            img: np.ndarray | jax.Array, cmap: list[tuple[float, ...]]
        ) -> jax.Array:
            return jnp.take(jnp.array(cmap), img + 1, axis=0)

        def _plot_image(
            ax: Axes, im, palette, n: int, title: str, labels: Iterable | None = None
        ):
            if labels is None:
                labels = range(n)
            cmap = sns.color_palette(palette, n)
            legend = [Patch(color=c, label=lbl) for c, lbl in zip(cmap, labels)]

            ax.imshow(_color_lut(im, [(0, 0, 0)] + cmap), origin="lower")
            ax.legend(
                handles=legend,
                ncols=-(n // -10),
                loc="center left",
                bbox_to_anchor=(1, 0.5),
            )
            ax.set(title=title)

        fig, axs = plt.subplots(nrows=1, ncols=2, figsize=(11, 6))

        _plot_image(
            axs[0],
            self.label_map.T,
            label_palette,
            self.n_labels,
            "Labels",
            self.labels,
        )
        _plot_image(axs[1], self.domains.T, domain_palette, self.n_domains, "Domains")

        if scale is not None:
            axs[0].add_artist(ScaleBar(*scale, **kwargs))
        fig.subplots_adjust(wspace=0.3)
        fig.tight_layout()
        return fig

    def plot_neighborhood_heatmap(
        self, *, palette=cc.glasbey_dark, **kwargs
    ) -> ClusterGrid:
        """Heatmap of the label enrichment of the domains.

        Parameters
        ----------
        palette : str, optional
            A valid argument for [seaborn.color_palette][]
        kwargs
            Other keyword arguments are passed to [seaborn.clustermap][]

        Returns
        -------
        seaborn.ClusterGrid
            Heatmap returned from [seaborn.clustermap][]
        """

        domains_flat = self.domains.ravel()
        # remove background
        not_background = domains_flat >= 0
        domains_flat = domains_flat[not_background]  # type: ignore

        order = np.argsort(domains_flat)

        domain_ids = np.unique(domains_flat)
        lut = dict(zip(domain_ids, sns.color_palette(palette, len(domain_ids))))

        g = sns.clustermap(
            _flatten_2d(self.neighborhoods)[not_background][order],
            row_colors=pd.Series(domains_flat[order]).map(lut).to_numpy(),
            **(_HEATMAP_KWARGS | kwargs),
        )
        g.ax_row_dendrogram.set_visible(False)
        g.ax_heatmap.set(xlabel=self.label_name)

        assert g.ax_row_colors is not None
        g.ax_row_colors.set_ylabel("bin")
        g.ax_row_colors.set_xlabel("domain", rotation="vertical")

        # Add black border to the colorbar
        assert g.ax_cbar is not None
        for spine in g.ax_cbar.spines.values():
            spine.set_edgecolor("black")
            spine.set_linewidth(1)
        return g

calculate_neighborhoods(binsize, radius, *, neighborhood='circle', normalize=True, sigma=1.0)

Calculate the neighborhoods.

The label map is binned and subsequently the neighborhood in terms of frequency per label calculated for each bin.

Parameters:

Name	Type	Description	Default
binsize	int	Size to bin the labeled grid by.	required
radius	int	Radius for the neighborhood aggregation. The size of the neighborhood will be 2 * binsize * (radius + 1)	required
neighborhood	str	Method for defining the neighborhood shape. Options: - "circle": A circular neighborhood based on Euclidean distance. - "square": A square neighborhood with all elements in the kernel. - "gaussian": A Gaussian-weighted neighborhood.	'circle'
normalize	bool	Whether to normalize the neighborhood of each bin (L1-norm).	True
sigma	float	Standard deviation for the Gaussian kernel, if neighborhood is 'gaussian'.	1.0

Source code in subdomain/_domaindetection.py

def calculate_neighborhoods(
    self,
    binsize: int,
    radius: int,
    *,
    neighborhood: str = "circle",
    normalize: bool = True,
    sigma: float = 1.0,
):
    """Calculate the neighborhoods.

    The label map is binned and subsequently the neighborhood in terms of frequency
    per label calculated for each bin.

    Parameters
    ----------
    binsize : int
        Size to bin the labeled grid by.
    radius : int
        Radius for the neighborhood aggregation. The size of the neighborhood will be
        `2 * binsize * (radius + 1)`
    neighborhood : str, optional
        Method for defining the neighborhood shape. Options:
            - "circle": A circular neighborhood based on Euclidean distance.
            - "square": A square neighborhood with all elements in the kernel.
            - "gaussian": A Gaussian-weighted neighborhood.
    normalize : bool, optional
        Whether to normalize the neighborhood of each bin (L1-norm).
    sigma : float, optional
        Standard deviation for the Gaussian kernel, if `neighborhood` is 'gaussian'.
    """

    match neighborhood:
        case "gaussian":
            neighborhood_fn = partial(_gaussian_neighborhood, sigma=sigma)

        case "square":
            neighborhood_fn = _square_neighborhood

        case "circle":
            neighborhood_fn = _circle_neighborhood

        case _:
            raise ValueError(
                f"Unknown `neighborhood`: {neighborhood}. "
                f"Supported types are: {sorted(_VALID_NEIGHH)}"
            )

    # TODO improve by allocating first?
    mtx = jnp.dstack(
        [
            neighborhood_fn(_bin_array(self.label_map == i, binsize), radius)
            for i in range(self.n_labels)
        ]
    )

    if normalize:
        l1_norm = mtx.sum(axis=2)
        # Avoid division by zero
        mtx /= l1_norm.at[l1_norm == 0].set(1e-10)[:, :, None]
        # set to nan
        mtx = mtx.at[l1_norm == 0, :].set(jnp.nan)
    self.neighborhoods = mtx
    self.binsize = binsize

cluster_neighborhoods(n_clusters, method='kmeans', *, gpu=False, random_state=1, **kwargs)

Cluster the aggregated neighborhoods.

Assigns a domain (cluster) to each bin in the calculated neighborhoods (requires to first run subdomain.SubDomain.calculate_neighborhoods).

Parameters:

Name	Type	Description	Default
n_clusters	int	Number of clusters.	required
method	str	TODO	'kmeans'
gpu	bool	Whether to use the GPU for KMeans clustering.	False
random_state	int	Random state for reproducibility.	1
kwargs		Other keyword arguments will be passed to sklearn.cluster.KMeans, cuml.cluster.KMeans, sklearn.mixture.GaussianMixture, or [torchgmm.bayes.GaussianMixture][] depending on the method and gpu parameters.	{}

Source code in subdomain/_domaindetection.py

def cluster_neighborhoods(
    self,
    n_clusters: int,
    method: str = "kmeans",
    *,
    gpu: bool = False,
    random_state: int = 1,
    **kwargs,
):
    """Cluster the aggregated neighborhoods.

    Assigns a domain (cluster) to each bin in the calculated neighborhoods (requires
    to first run [subdomain.SubDomain.calculate_neighborhoods][]).

    Parameters
    ----------
    n_clusters : int
        Number of clusters.
    method : str, optional
        TODO
    gpu : bool, optional
        Whether to use the GPU for KMeans clustering.
    random_state : int, optional
        Random state for reproducibility.
    kwargs
        Other keyword arguments will be passed to [sklearn.cluster.KMeans][], [cuml.cluster.KMeans][],
        [sklearn.mixture.GaussianMixture][], or [torchgmm.bayes.GaussianMixture][] depending on
        the `method` and `gpu` parameters.
    """
    torch_tensor = False
    match method:
        case "kmeans":
            if gpu:
                import cuml

                model = cuml.cluster.KMeans(
                    n_clusters=n_clusters,
                    random_state=random_state,
                    output_type="numpy",
                    **kwargs,
                )
            else:
                model = KMeans(
                    n_clusters=n_clusters, random_state=random_state, **kwargs
                )
        case "gmm":
            if gpu:
                import torch
                from torchgmm.bayes import GaussianMixture as TorchGaussianMixture

                # TODO: how to seed
                torch_tensor = True
                model = TorchGaussianMixture(num_components=n_clusters, **kwargs)
            else:
                model = GaussianMixture(
                    n_components=n_clusters, random_state=random_state, **kwargs
                )
        case _:
            raise ValueError(
                f"Unknown `method`: {method}. "
                f"Supported types are: {sorted(_VALID_CLUSTER)}"
            )

    mtx_flat = _flatten_2d(self.neighborhoods)
    not_nan = ~jnp.isnan(mtx_flat).any(axis=1)

    domain = np.full(mtx_flat.shape[0], -1, dtype=np.int16)
    if torch_tensor:
        # TODO is this needed?
        prediction = model.fit_predict(
            torch.tensor(mtx_flat[not_nan], dtype=torch.float32).cuda()
        ).numpy(force=True)
    else:
        prediction = model.fit_predict(mtx_flat[not_nan])
    domain[not_nan] = prediction
    self.domains = domain.reshape(self.neighborhoods.shape[:2])
    self.n_domains = n_clusters

domain_composition()

Label composition of each domain.

Returns:

Type	Description
DataFrame	Label composition.

Source code in subdomain/_domaindetection.py

def domain_composition(self) -> pd.DataFrame:
    """Label composition of each domain.

    Returns
    -------
    pandas.DataFrame
        Label composition.
    """
    name = self.label_name

    domain_composition = (
        pd.DataFrame(
            {
                name: self.label_map.ravel(),
                "domain": self.rescale_domain_map().ravel(),
            }
        )
        .loc[lambda df: df[name].ge(0)]
        .groupby(["domain", name])
        .size()
    )
    domain_composition /= domain_composition.groupby("domain").transform("sum")
    return (
        domain_composition.to_frame("fraction")
        .reset_index()
        .pivot(index="domain", columns=name, values="fraction")
        .fillna(0)
    )

domain_neighborhoods()

Average neighborhood of the domains.

Returns:

Type	Description
DataFrame	Average neighborhood.

Source code in subdomain/_domaindetection.py

def domain_neighborhoods(self) -> pd.DataFrame:
    """Average neighborhood of the domains.

    Returns
    -------
    pandas.DataFrame
        Average neighborhood.
    """
    neighbor_fractions = (
        pd.DataFrame(_flatten_2d(self.neighborhoods), columns=self.labels)
        .assign(domain=self.domains.ravel())
        .loc[lambda df: df["domain"].ge(0)]
        .groupby("domain")
        .agg("mean")
    )
    neighbor_fractions.columns.name = self.label_name
    return neighbor_fractions

identify_domains(n_clusters, binsize=8, radius=10, *, neighborhood='circle', normalize=True, sigma=1.0, clustering_method='kmeans', gpu=False, random_state=1, **kwargs)

Identify domains from labeled grid.

This is a wrapper around subdomain.SubDomain.calculate_neighborhoods and subdomain.SubDomain.cluster_neighborhoods.

If the neighborhood has already been calculated (and the parameters do not need to be changed) it is more efficient to just cluster the domains rather than recalculating the neighborhoods.

Parameters:

Name	Type	Description	Default
n_clusters	int	Number of domains (clusters) to identify.	required
binsize	int	Size to bin the labeled grid by.	8
radius	int	Radius for the neighborhood aggregation. The size of the neighborhood will be 2 * binsize * (radius + 1)	10
neighborhood	str	Method for defining the neighborhood shape. Options: - 'circle': A circular neighborhood based on Euclidean distance. - 'square': A square neighborhood with all elements in the kernel. - 'gaussian': A Gaussian-weighted neighborhood.	'circle'
normalize	bool	Whether to normalize the neighborhood of each bin (L1-norm).	True
sigma	float	TODO	1.0
clustering_method	str	The clustering method to use. Options are: - 'kmeans': Use KMeans clustering. - 'gmm': Use Gaussian Mixture Model clustering.	'kmeans'
gpu	bool	Whether to use the GPU for KMeans clustering. The neighborhood aggregation will run by default on GPU if available.	False
random_state	int	Random state for reproducibility.	1
kwargs		Other keyword arguments will be passed to the clustering method. See subdomain.SubDomain.cluster_neighborhoods for details.	{}

Source code in subdomain/_domaindetection.py

def identify_domains(
    self,
    n_clusters: int,
    binsize: int = 8,
    radius: int = 10,
    *,
    neighborhood: str = "circle",
    normalize: bool = True,
    sigma: float = 1.0,
    clustering_method: str = "kmeans",
    gpu: bool = False,
    random_state: int = 1,
    **kwargs,
):
    """Identify domains from labeled grid.

    This is a wrapper around [subdomain.SubDomain.calculate_neighborhoods][] and
    [subdomain.SubDomain.cluster_neighborhoods][].

    If the neighborhood has already been calculated (and the parameters do not need
    to be changed) it is more efficient to just cluster the domains rather than
    recalculating the neighborhoods.

    Parameters
    ----------
    n_clusters : int
        Number of domains (clusters) to identify.
    binsize : int
        Size to bin the labeled grid by.
    radius : int
        Radius for the neighborhood aggregation. The size of the neighborhood will be
        `2 * binsize * (radius + 1)`
    neighborhood : str, optional
        Method for defining the neighborhood shape. Options:
        - 'circle': A circular neighborhood based on Euclidean distance.
        - 'square': A square neighborhood with all elements in the kernel.
        - 'gaussian': A Gaussian-weighted neighborhood.
    normalize : bool, optional
        Whether to normalize the neighborhood of each bin (L1-norm).
    sigma : float, optional
        TODO
    clustering_method : str, optional
        The clustering method to use. Options are:
        - 'kmeans': Use KMeans clustering.
        - 'gmm': Use Gaussian Mixture Model clustering.
    gpu: bool, optional
        Whether to use the GPU for KMeans clustering. The neighborhood aggregation will
        run by default on GPU if available.
    random_state : int, optional
        Random state for reproducibility.
    kwargs
        Other keyword arguments will be passed to the clustering method.
        See [subdomain.SubDomain.cluster_neighborhoods][] for details.
    """
    if neighborhood not in _VALID_NEIGHH:
        raise ValueError(
            f"Unknown `neighborhood`: {neighborhood}. "
            f"Supported types are: {sorted(_VALID_NEIGHH)}"
        )
    if clustering_method not in _VALID_CLUSTER:
        raise ValueError(
            f"Unknown `clustering_method`: {clustering_method}. "
            f"Supported types are: {sorted(_VALID_CLUSTER)}"
        )

    self.calculate_neighborhoods(
        binsize, radius, neighborhood=neighborhood, normalize=normalize, sigma=sigma
    )
    self.cluster_neighborhoods(
        n_clusters, clustering_method, gpu=gpu, random_state=random_state, **kwargs
    )

plot_domains(domain_palette=cc.glasbey_dark, label_palette=cc.glasbey_light, *, scale=None, **kwargs)

Spatial plot of domains and labeled grid.

Parameters:

Name	Type	Description	Default
domain_palette		Palette to use for the domain plot. Must be a valid argument for seaborn.color_palette	glasbey_dark
label_palette		Palette to use for the labeled grid plot. Must be a valid argument for seaborn.color_palette	glasbey_light
scale	tuple[float, str] | None	Size of a pixel in the original labeled grid as a tuple of the value and the unit (must be one of nm, um, ...) e.g. (5, 'um').	None
kwargs		Other keyword arguments are passed to matplotlib-scalebar.ScaleBar	{}

Returns:

Type	Description
Figure

Source code in subdomain/_domaindetection.py

def plot_domains(
    self,
    domain_palette=cc.glasbey_dark,
    label_palette=cc.glasbey_light,
    *,
    scale: tuple[float, str] | None = None,
    **kwargs,
) -> Figure:
    """Spatial plot of domains and labeled grid.

    Parameters
    ----------
    domain_palette
        Palette to use for the domain plot. Must be a valid argument for
        [seaborn.color_palette][]
    label_palette
        Palette to use for the labeled grid plot. Must be a valid argument for
        [seaborn.color_palette][]
    scale : tuple[float, str] | None
        Size of a pixel in the original labeled grid as a tuple of the value and
        the unit (must be one of nm, um, ...) e.g. `(5, 'um')`.
    kwargs
        Other keyword arguments are passed to `matplotlib-scalebar.ScaleBar`

    Returns
    -------
    matplotlib.figure.Figure
    """

    def _color_lut(
        img: np.ndarray | jax.Array, cmap: list[tuple[float, ...]]
    ) -> jax.Array:
        return jnp.take(jnp.array(cmap), img + 1, axis=0)

    def _plot_image(
        ax: Axes, im, palette, n: int, title: str, labels: Iterable | None = None
    ):
        if labels is None:
            labels = range(n)
        cmap = sns.color_palette(palette, n)
        legend = [Patch(color=c, label=lbl) for c, lbl in zip(cmap, labels)]

        ax.imshow(_color_lut(im, [(0, 0, 0)] + cmap), origin="lower")
        ax.legend(
            handles=legend,
            ncols=-(n // -10),
            loc="center left",
            bbox_to_anchor=(1, 0.5),
        )
        ax.set(title=title)

    fig, axs = plt.subplots(nrows=1, ncols=2, figsize=(11, 6))

    _plot_image(
        axs[0],
        self.label_map.T,
        label_palette,
        self.n_labels,
        "Labels",
        self.labels,
    )
    _plot_image(axs[1], self.domains.T, domain_palette, self.n_domains, "Domains")

    if scale is not None:
        axs[0].add_artist(ScaleBar(*scale, **kwargs))
    fig.subplots_adjust(wspace=0.3)
    fig.tight_layout()
    return fig

plot_neighborhood_heatmap(*, palette=cc.glasbey_dark, **kwargs)

Heatmap of the label enrichment of the domains.

Parameters:

Name	Type	Description	Default
palette	str	A valid argument for seaborn.color_palette	glasbey_dark
kwargs		Other keyword arguments are passed to seaborn.clustermap	{}

Returns:

Type	Description
ClusterGrid	Heatmap returned from seaborn.clustermap

Source code in subdomain/_domaindetection.py

def plot_neighborhood_heatmap(
    self, *, palette=cc.glasbey_dark, **kwargs
) -> ClusterGrid:
    """Heatmap of the label enrichment of the domains.

    Parameters
    ----------
    palette : str, optional
        A valid argument for [seaborn.color_palette][]
    kwargs
        Other keyword arguments are passed to [seaborn.clustermap][]

    Returns
    -------
    seaborn.ClusterGrid
        Heatmap returned from [seaborn.clustermap][]
    """

    domains_flat = self.domains.ravel()
    # remove background
    not_background = domains_flat >= 0
    domains_flat = domains_flat[not_background]  # type: ignore

    order = np.argsort(domains_flat)

    domain_ids = np.unique(domains_flat)
    lut = dict(zip(domain_ids, sns.color_palette(palette, len(domain_ids))))

    g = sns.clustermap(
        _flatten_2d(self.neighborhoods)[not_background][order],
        row_colors=pd.Series(domains_flat[order]).map(lut).to_numpy(),
        **(_HEATMAP_KWARGS | kwargs),
    )
    g.ax_row_dendrogram.set_visible(False)
    g.ax_heatmap.set(xlabel=self.label_name)

    assert g.ax_row_colors is not None
    g.ax_row_colors.set_ylabel("bin")
    g.ax_row_colors.set_xlabel("domain", rotation="vertical")

    # Add black border to the colorbar
    assert g.ax_cbar is not None
    for spine in g.ax_cbar.spines.values():
        spine.set_edgecolor("black")
        spine.set_linewidth(1)
    return g

rescale_domain_map()

Rescale domain map to original labeled grid size, i.e., prior to binning.

Source code in subdomain/_domaindetection.py

def rescale_domain_map(self) -> np.ndarray:
    """Rescale domain map to original labeled grid size, i.e., prior to binning."""
    rescaled_domains = np.repeat(
        np.repeat(self.domains, self.binsize, axis=0), self.binsize, axis=1
    )[: self.label_map.shape[0], : self.label_map.shape[1]]
    return rescaled_domains