grassp.tl.merge_clusters_go

grassp.tl.merge_clusters_go#

merge_clusters_go(adata, pv_cutoff=0.05, connectivity_lower=0.5, cluster_col='leiden', gene_sets_path=None, species='hsap', deduplicate_terms=True, gene_name_key='Gene_name_canonical', compartment_col='Cell_compartment', key_added='leiden_merged', linkage_method='average', verbose=True, plot_iterations=False, plot_dendrogram=False, merge_method='ora', merge_threshold=0.0, max_active=4, n_steps=200000, n_restarts=3, seed=0)[source]#

Iteratively merge overclustered Leiden clusters using PAGA and GO enrichment.

Candidate pairs are determined from cherry pairs of a dendrogram built from PAGA connectivity (paga_dendrogram()). Each round:

  1. Build the PAGA-connectivity dendrogram and identify flat cherry pairs.

  2. For each pair with connectivity ≥ connectivity_lower, run a two-sided Fisher’s exact test on the best GO term of each cluster.

  3. Pairs where both tests are non-significant at pv_cutoff (or both clusters share the same top term) become merge candidates.

  4. Greedily merge non-overlapping candidates ordered by decreasing min p-value (least significant first).

  5. Recompute enrichment annotation and rebuild the dendrogram; repeat until no merges occur.

Results are written to adata.obs[key_added].

Parameters:
adata AnnData

AnnData object with proteins as observations. Must already have cluster_col populated (e.g. after scanpy.tl.leiden()) and a precomputed KNN graph in adata.obsp (e.g. after grassp.pp.neighbors()).

pv_cutoff float (default: 0.05)

Significance threshold before Bonferroni correction.

connectivity_lower float (default: 0.5)

Minimum PAGA connectivity to consider a cherry pair for merging. Pairs below this are ignored regardless of enrichment.

cluster_col str (default: 'leiden')

adata.obs column with initial cluster labels.

gene_sets_path Union[str, dict, None] (default: None)

Path to a GMT file, a gseapy library name, a pre-loaded dict[str, list[str]], or None (uses the consolidated UniProt subcellular compartment gene sets for the chosen species).

species Literal['hsap', 'mmus', 'scer'] (default: 'hsap')

Species code used to pick the default gene-set file when gene_sets_path is None. One of "hsap" (human, consolidated_goterms_human.gmt), "mmus" (mouse, consolidated_goterms_mouse.gmt), or "scer" (yeast, consolidated_goterms_yeast.gmt). Default "hsap". Ignored when an explicit gene_sets_path is provided.

deduplicate_terms bool (default: True)

If True (default), collapse gene sets with identical membership to a single term (keeping the first-seen name) before merging, so synonymous / duplicate compartments in fine ontologies do not distort the tests.

gene_name_key str (default: 'Gene_name_canonical')

adata.obs column with gene/protein names used for enrichment.

compartment_col str (default: 'Cell_compartment')

adata.obs column that will hold per-protein compartment annotations (written by calculate_cluster_enrichment()).

key_added str (default: 'leiden_merged')

adata.obs column to write final merged cluster labels to.

linkage_method str (default: 'average')

Linkage algorithm for paga_dendrogram().

verbose bool (default: True)

Print round-by-round merging decisions.

plot_iterations bool (default: False)

If True, plot a UMAP after each round showing the current clustering and compartment annotation side by side (requires a precomputed UMAP).

plot_dendrogram bool (default: False)

If True, plot the initial PAGA dendrogram after convergence with leaf lines colored by compartment term and merge nodes colored by p-value.

merge_method Literal['ora', 'mgsa_evidence'] (default: 'ora')

How to decide merges.

  • 'ora' (default): pairwise Fisher differential-enrichment test on each cluster’s top term.

  • 'mgsa_evidence': Bayesian model comparison — merge iff BF(c1∪c2) - BF(c1) - BF(c2) >= merge_threshold where BF(S) = logE(S) - logE_null(S) is the MGSA log-Bayes-factor of “some compartment active” vs. “nothing active”. This merges by default (no-signal pairs score ~0) and only keeps clusters apart when there is distinct evidence against merging (negative score, i.e. the parts are different compartments). Handles the small-cluster early-merge regime. Self-consistent with the MGSA final annotation.

merge_threshold float (default: 0.0)

Only for merge_method='mgsa_evidence': the minimum merge score to merge. 0.0 (default) merges unless there is evidence against; a negative value merges even in the face of weak evidence against; a positive value requires positive evidence for merging.

max_active int (default: 4)

For merge_method='mgsa_evidence': cap on simultaneously active sets in the exact enumeration (forwarded to calculate_mgsa() / mgsa()).

n_steps int (default: 200000)

MGSA MCMC settings, used only if a run falls back to method='mcmc' (the exact method is used for the small compartment vocabulary). Ignored for merge_method='ora'.

n_restarts int (default: 3)

MGSA MCMC settings, used only if a run falls back to method='mcmc' (the exact method is used for the small compartment vocabulary). Ignored for merge_method='ora'.

seed Optional[int] (default: 0)

MGSA MCMC settings, used only if a run falls back to method='mcmc' (the exact method is used for the small compartment vocabulary). Ignored for merge_method='ora'.

Return type:

None