The clustering stability (cs) accessor

The clustering stability (cs) accessor#

The clustering stability accessor provides metrics for assessing the stability of clustering results across different resolutions and random subsets of genes.

segtraq.cs.clustering_stability.adjusted_rand_index(sdata: SpatialData, resolution: float = 0.2, frac_cells_subset: float = 0.63, tables_key: str = 'table', key_prefix: str = 'leiden_subset', use_hvg: bool | None = None, exclude_gene_prefixes: str | list[str] | tuple[str, ...] | None = ('MT-', 'RPL', 'RPS'), n_neighbors: int = 15, n_pcs: int = 50, target_sum: float | None = None, inplace: bool = True, leiden_kwargs: dict | None = None) → float#

Compute the clustering stability using pairwise adjusted Rand index (ARI) on random subset of cells.

Parameters:

  • sdata (sd.SpatialData) – The SpatialData object containing clustering information.

  • resolution (float, optional) – The resolution parameter for Leiden clustering, by default 0.2.

  • frac_cells_subset (float, optional) – The fraction of cells to subset for clustering, by default 0.63.

  • tables_key (str, optional) – The key in sdata.tables where the relevant AnnData is stored, by default “table”.

  • key_prefix (str, optional) – The prefix for the keys under which the clustering results are stored, by default “leiden_subset”.

  • use_hvg (bool or None, optional) – If None, use 2,000 HVGs for PCA when the panel contains more than 8,000 genes. If True, always use HVGs. If False, use all genes.

  • exclude_gene_prefixes (str, list of str, tuple of str, or None, default=("MT-", "RPL", "RPS")) – Gene prefix(es) to exclude from the HVG set. If None, no genes are excluded based on their prefix. Has no effect if HVGs are not used.

  • n_neighbors (int, optional) – Number of neighbors to use for computing the connectivity matrix. Default is 15.

  • n_pcs (int, optional) – Number of principal components to compute for PCA. Default is 50.

  • target_sum (float | None, optional) – Target sum for normalization in scanpy.pp.normalize_total() before PCA. Default is None.

  • inplace (bool, optional) – Whether to store the computed ARI in sdata.uns, by default True.

  • leiden_kwargs (dict, optional) – Additional keyword arguments to pass to scanpy.tl.leiden(). For example, flavor=’igraph’ can be used to specify the Leiden implementation.

Returns:

The average pairwise ARI across the specified cluster keys.

Return type:

float

segtraq.cs.clustering_stability.cluster_connectedness(sdata: SpatialData, resolution: float | list[float] = 0.2, use_weights: bool = False, tables_key: str = 'table', key_prefix: str = 'leiden_subset', random_state: int = 42, cell_type_key: str | None = None, use_hvg: bool | None = None, exclude_gene_prefixes: str | list[str] | tuple[str, ...] | None = ('MT-', 'RPL', 'RPS'), n_neighbors: int = 15, n_pcs: int = 50, target_sum: float | None = None, inplace: bool = True, leiden_kwargs: dict | None = None) → float#

Compute cluster connectedness for different Leiden clustering resolutions and report the best (highest) one. If a cell_type_key is provided, compute the connectedness for that clustering only.

Parameters:

  • sdata (sd.SpatialData) – The SpatialData object containing clustering information.

  • resolution (float or list of float, optional) – The resolution parameter(s) for Leiden clustering, by default 0.2.

  • use_weights (bool) – Use edge weights to evaluate connectedness. If false, fraction of equal neighbors is used.

  • tables_key (str, optional) – The key in sdata.tables where the relevant AnnData is stored, by default “table”.

  • key_prefix (str, optional) – Prefix for clustering keys in .obs, by default “leiden_subset”.

  • random_state (int, optional) – Seed for reproducibility, by default 42.

  • cell_type_key (str, optional) – If provided, compute cluster connectedness for this clustering only.

  • use_hvg (bool or None, optional) – If None, use 2,000 HVGs for PCA when the panel contains more than 8,000 genes. If True, always use HVGs. If False, use all genes.

  • exclude_gene_prefixes (str, list of str, tuple of str, or None, default=("MT-", "RPL", "RPS")) – Gene prefix(es) to exclude from the HVG set. If None, no genes are excluded based on their prefix. Has no effect if HVGs are not used.

  • n_neighbors (int, optional) – Number of neighbors to use for computing the connectivity matrix. Default is 15.

  • n_pcs (int, optional) – Number of principal components to compute for PCA. Default is 50.

  • target_sum (float | None, optional) – Target sum for normalization in scanpy.pp.normalize_total() before PCA. Default is None.

  • inplace (bool, optional) – Whether to store the computed cluster connectedness in sdata.uns, by default True.

  • leiden_kwargs (dict, optional) – Additional keyword arguments to pass to scanpy.tl.leiden(). For example, flavor=’igraph’ can be used to specify the Leiden implementation.

Returns:

The best (highest) cluster connectedness across resolutions.

Return type:

float

segtraq.cs.clustering_stability.purity(sdata: SpatialData, resolution: float = 0.2, frac_cells_subset: float = 0.63, tables_key: str = 'table', key_prefix: str = 'leiden_subset', use_hvg: bool | None = None, exclude_gene_prefixes: str | list[str] | tuple[str, ...] | None = ('MT-', 'RPL', 'RPS'), n_neighbors: int = 15, n_pcs: int = 50, target_sum: float | None = None, inplace: bool = True, leiden_kwargs: dict | None = None) → float#

Compute the clustering stability using pairwise purity on random subsets of cells.

Parameters:

  • sdata (sd.SpatialData) – The SpatialData object containing clustering information.

  • resolution (float, optional) – The resolution parameter for Leiden clustering, by default 0.2.

  • tables_key (str, optional) – The key in sdata.tables where the relevant AnnData is stored, by default “table”.

  • frac_cells_subset (float, optional) – The fraction of cells to subset for clustering, by default 0.63.

  • key_prefix (str, optional) – The prefix for the keys under which the clustering results are stored, by default “leiden_subset”.

  • use_hvg (bool or None, optional) – If None, use 2,000 HVGs for PCA when the panel contains more than 8,000 genes. If True, always use HVGs. If False, use all genes.

  • exclude_gene_prefixes (str, list of str, tuple of str, or None, default=("MT-", "RPL", "RPS")) – Gene prefix(es) to exclude from the HVG set. If None, no genes are excluded based on their prefix. Has no effect if HVGs are not used.

  • n_neighbors (int, optional) – Number of neighbors to use for computing the connectivity matrix. Default is 15.

  • n_pcs (int, optional) – Number of principal components to compute for PCA. Default is 50.

  • target_sum (float | None, optional) – Target sum for normalization in scanpy.pp.normalize_total() before PCA. Default is None.

  • inplace (bool, optional) – Whether to store the computed purity in sdata.uns, by default True.

  • leiden_kwargs (dict, optional) – Additional keyword arguments to pass to scanpy.tl.leiden(). For example, flavor=’igraph’ can be used to specify the Leiden implementation.

Returns:

The average pairwise purity across the specified cluster keys.

Return type:

float

segtraq.cs.clustering_stability.silhouette_score(sdata: SpatialData, resolution: float | list[float] = 0.2, metric: str = 'euclidean', tables_key: str = 'table', key_prefix: str = 'leiden_subset', random_state: int = 42, cell_type_key: str | None = None, use_hvg: bool | None = None, exclude_gene_prefixes: str | list[str] | tuple[str, ...] | None = ('MT-', 'RPL', 'RPS'), n_neighbors: int = 15, n_pcs: int = 50, target_sum: float | None = None, inplace: bool = True, leiden_kwargs: dict | None = None) → float#

Compute the silhouette score for different resolutions and report the best one. If a cell_type_key is provided, compute the silhouette score for provided labels.

Parameters:

  • sdata (sd.SpatialData) – The SpatialData object containing clustering information.

  • resolution (float, optional) – The resolution parameter for Leiden clustering, by default 0.2.

  • metric (str, optional) – The metric to use for silhouette score calculation, by default “euclidean”.

  • tables_key (str, optional) – The key in sdata.tables where the relevant AnnData is stored, by default “table”.

  • key_prefix (str, optional) – The prefix for the keys under which the clustering results are stored, by default “leiden_subset”.

  • random_state (int, optional) – Seed for reproducibility, by default 42.

  • cell_type_key (str, optional) – If provided, compute the silhouette score for provided labels.

  • use_hvg (bool or None, optional) – If None, use 2,000 HVGs for PCA when the panel contains more than 8,000 genes. If True, always use HVGs. If False, use all genes.

  • exclude_gene_prefixes (str, list of str, tuple of str, or None, default=("MT-", "RPL", "RPS")) – Gene prefix(es) to exclude from the HVG set. If None, no genes are excluded based on their prefix. Has no effect if HVGs are not used.

  • n_neighbors (int, optional) – Number of neighbors to use for computing the connectivity matrix. Default is 15.

  • n_pcs (int, optional) – Number of principal components to compute for PCA. Default is 50.

  • target_sum (float | None, optional) – Target sum for normalization in scanpy.pp.normalize_total() before PCA. Default is None.

  • inplace (bool, optional) – Whether to store the computed silhouette score in sdata.uns, by default True.

  • leiden_kwargs (dict, optional) – Additional keyword arguments to pass to scanpy.tl.leiden(). For example, flavor=’igraph’ can be used to specify the Leiden implementation.

Returns:

The silhouette score of the clustering.

Return type:

float

Contents