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, tables_gene_key=None, resolution=0.2, frac_cells_subset=0.63, tables_key='table', key_prefix='leiden_subset', use_hvg=None, exclude_gene_prefixes=('MT-', 'RPL', 'RPS'), n_neighbors=15, n_pcs=50, target_sum=None, inplace=True, leiden_kwargs=None, n_jobs=None)#

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

Parameters:

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

  • tables_gene_key (str or None, default None) – Column in sdata.tables[tables_key].var containing gene identifiers. If None, sdata.tables[tables_key].var_names are used.

  • 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, optional) – Gene prefixes excluded from PCA feature selection. By default (("MT-", "RPL", "RPS")), mitochondrial and ribosomal genes are excluded. This filtering is applied independently of HVG selection. Set to None to use all genes.

  • 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.

  • n_jobs (int or None, optional) – Number of threads used by numba, BLAS and OpenMP for PCA, neighbor graph construction and clustering. If None, uses segtraq.settings.n_jobs (default: 1). Set to -1 to use all CPUs available to the current process. Results are only reproducible for a fixed number of threads.

Returns:

The average pairwise ARI across the specified cluster keys.

Return type:

float

segtraq.cs.clustering_stability.connectedness(sdata, tables_gene_key=None, resolution=0.2, use_weights=False, tables_key='table', key_prefix='leiden_subset', random_state=42, cell_type_key=None, use_hvg=None, exclude_gene_prefixes=('MT-', 'RPL', 'RPS'), n_neighbors=15, n_pcs=50, target_sum=None, inplace=True, leiden_kwargs=None, n_jobs=None)#

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 (SpatialData) – The SpatialData object containing clustering information.

  • tables_gene_key (str or None, default None) – Column in sdata.tables[tables_key].var containing gene identifiers. If None, sdata.tables[tables_key].var_names are used.

  • 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, optional) – Gene prefixes excluded from PCA feature selection. By default (("MT-", "RPL", "RPS")), mitochondrial and ribosomal genes are excluded. This filtering is applied independently of HVG selection. Set to None to use all genes.

  • 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.

  • n_jobs (int or None, optional) – Number of threads used by numba, BLAS and OpenMP for PCA, neighbor graph construction and clustering. If None, uses segtraq.settings.n_jobs (default: 1). Set to -1 to use all CPUs available to the current process. Results are only reproducible for a fixed number of threads.

Returns:

The best (highest) cluster connectedness across resolutions.

Return type:

float

segtraq.cs.clustering_stability.purity(sdata, tables_gene_key=None, resolution=0.2, frac_cells_subset=0.63, tables_key='table', key_prefix='leiden_subset', use_hvg=None, exclude_gene_prefixes=('MT-', 'RPL', 'RPS'), n_neighbors=15, n_pcs=50, target_sum=None, inplace=True, leiden_kwargs=None, n_jobs=None)#

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

Parameters:

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

  • tables_gene_key (str or None, default None) – Column in sdata.tables[tables_key].var containing gene identifiers. If None, sdata.tables[tables_key].var_names are used.

  • 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, optional) – Gene prefixes excluded from PCA feature selection. By default (("MT-", "RPL", "RPS")), mitochondrial and ribosomal genes are excluded. This filtering is applied independently of HVG selection. Set to None to use all genes.

  • 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.

  • n_jobs (int or None, optional) – Number of threads used by numba, BLAS and OpenMP for PCA, neighbor graph construction and clustering. If None, uses segtraq.settings.n_jobs (default: 1). Set to -1 to use all CPUs available to the current process. Results are only reproducible for a fixed number of threads.

Returns:

The average pairwise purity across the specified cluster keys.

Return type:

float

segtraq.cs.clustering_stability.silhouette_score(sdata, tables_gene_key=None, resolution=0.2, metric='euclidean', tables_key='table', key_prefix='leiden_subset', random_state=42, cell_type_key=None, use_hvg=None, exclude_gene_prefixes=('MT-', 'RPL', 'RPS'), n_neighbors=15, n_pcs=50, target_sum=None, inplace=True, leiden_kwargs=None, n_jobs=None)#

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 (SpatialData) – The SpatialData object containing clustering information.

  • tables_gene_key (str or None, default None) – Column in sdata.tables[tables_key].var containing gene identifiers. If None, sdata.tables[tables_key].var_names are used.

  • 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, optional) – Gene prefixes excluded from PCA feature selection. By default (("MT-", "RPL", "RPS")), mitochondrial and ribosomal genes are excluded. This filtering is applied independently of HVG selection. Set to None to use all genes.

  • 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.

  • n_jobs (int or None, optional) – Number of threads used by numba, BLAS and OpenMP for PCA, neighbor graph construction and clustering. If None, uses segtraq.settings.n_jobs (default: 1). Set to -1 to use all CPUs available to the current process. Results are only reproducible for a fixed number of threads.

Returns:

The silhouette score of the clustering.

Return type:

float

Contents