grassp.tl.calculate_mgsa

calculate_mgsa(data, cluster_key='leiden', gene_name_key='Gene_name_canonical', gene_sets=None, species='hsap', obs_key_added='Cell_compartment_mgsa', method='auto', max_active=4, alpha_prior=None, beta_prior=None, min_posterior=0.5, deduplicate_terms=True, n_steps=1000000, n_restarts=5, seed=0, posterior_uns_key=None, return_result=True, inplace=True, verbose=True, **mgsa_kwargs)

Model-based gene-set analysis (MGSA) per cluster.

The MGSA analogue of calculate_cluster_enrichment(): for each category in data.obs[cluster_key] it runs mgsa() with the cluster’s genes as the study set and all genes as the population, then records the most probable active compartment. Unlike a per-term hypergeometric test, MGSA explains each cluster’s genes jointly, so overlapping compartments compete and a redundant one (e.g. Lipid droplet vs. Endoplasmic reticulum) is only reported active if it explains genes the other cannot.

Parameters:

data AnnData

AnnData with proteins as observations.

cluster_key str (default: 'leiden')

Categorical column in data.obs with cluster labels.

gene_name_key str (default: 'Gene_name_canonical')

Column in data.obs with gene identifiers (matching the gene sets).

gene_sets Union[str, Mapping[str, Sequence[str]], None] (default: None)

Gene-set source passed to load_gmt(); None uses the bundled consolidated UniProt compartment sets for species.

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

Species code for the bundled gene sets when gene_sets is None.

obs_key_added str (default: 'Cell_compartment_mgsa')

Column to write the top active compartment per cluster to (NaN if the top posterior is below min_posterior).

method str (default: 'auto')

Forwarded to mgsa(). method="auto" (default) uses the exact enumeration for the small consolidated compartment vocabulary — fast and variance-free — and only falls back to MCMC for GO-sized gene-set libraries. max_active caps the exact enumeration (see mgsa()).

max_active int (default: 4)

Forwarded to mgsa(). method="auto" (default) uses the exact enumeration for the small consolidated compartment vocabulary — fast and variance-free — and only falls back to MCMC for GO-sized gene-set libraries. max_active caps the exact enumeration (see mgsa()).

min_posterior float (default: 0.5)

Posterior-activity threshold for assigning the top compartment label.

deduplicate_terms bool (default: True)

Forwarded to load_gmt(); if True (default) sets with identical gene membership are collapsed to one term, so synonymous/duplicate compartments (e.g. PEROXISOME ≡ MICROBODY in fine ontologies) do not split the posterior mass and dilute the top compartment below min_posterior.

n_steps int (default: 1000000)

Forwarded to mgsa(); only used when the run falls back to method="mcmc" (ignored for the exact path).

n_restarts int (default: 5)

Forwarded to mgsa(); only used when the run falls back to method="mcmc" (ignored for the exact path).

seed Optional[int] (default: 0)

Forwarded to mgsa(); only used when the run falls back to method="mcmc" (ignored for the exact path).

posterior_uns_key Optional[str] (default: None)

uns key for the full (cluster x compartment) posterior activity matrix. Defaults to f"{obs_key_added}_posterior".

return_result bool (default: True)

If True return the posterior DataFrame.

inplace bool (default: True)

If True annotate data in place.

verbose bool (default: True)

Print per-cluster progress.

**mgsa_kwargs

Extra keyword arguments forwarded to mgsa() (e.g. grids, thin).

alpha_prior callable | None

beta_prior callable | None

Return type:

Optional[DataFrame]

Returns:

Optional[pandas.DataFrame] The (cluster x compartment) posterior activity matrix if return_result else None. When inplace the top-compartment labels are written to data.obs[obs_key_added], the marginal posterior matrix to data.uns[posterior_uns_key], and the per-cluster MAP active-set indicator (0/1) to data.uns[f"{obs_key_added}_map"]. The MAP matrix is the recommended input to mgsa_to_cluster_distribution() (use_map=True).