grassp.tl.soft_cluster_annotation

grassp.tl.soft_cluster_annotation#

soft_cluster_annotation(data, enr_res=None, cluster_key='leiden', key_added='soft_annotation', cluster_distribution=None, ranking_metric='Adjusted P-value Bonferroni', threshold=0.05, temperature=1.0, s0=0.0, s_max=300.0, unknown_label='unknown', weight_by='evidence', class_balance=True, min_probability=None, obsp_key='connectivities', method='propagation', iterative=False, alpha=0.8, seed_obsm_key=None, seed_categories_uns_key=None, resolve='threshold', unknown_gate=0.5, null='permutation', n_permutations=1000, alpha_fdr=0.05, multi_label_cum=0.8, single_eff_k=1.5, max_labels=3, min_secondary_mass=0.2, canonical_order=False, random_state=0, set_colors=True, verbose=True)[source]#

Soft, uncertainty-aware version of the cluster-annotation pipeline.

Ties together the three steps needed to propagate enrichment uncertainty rather than a single hard top term per cluster:

  1. Convert the per-(cluster, term) enrichment table enr_res into a per-cluster probability distribution over a shared compartment vocabulary (plus an explicit unknown class) via enrichment_to_cluster_distribution().

  2. Broadcast each cluster’s distribution to its member proteins, producing a soft seed matrix stored in data.obsm[f"{key_added}_seed"] with the category order in data.uns[f"{key_added}_categories"].

  3. Propagate the soft seed over the neighbour graph with competitive_propagation(), writing the propagated distribution to data.obsm[f"{key_added}_probabilities"] and the argmax label (with unknown mapped to NaN) to data.obs[key_added].

Parameters:
data AnnData

AnnData with a populated neighbour graph and cluster_key in data.obs.

enr_res DataFrame | None (default: None)

Enrichment table from calculate_cluster_enrichment() (return_enrichment_res=True), computed on the same cluster_key. Required unless cluster_distribution is given.

cluster_key str (default: 'leiden')

Column in data.obs (and enr_res) with the cluster labels the enrichment was computed on.

key_added str (default: 'soft_annotation')

Base name for the outputs described above.

cluster_distribution tuple[DataFrame, list] | None (default: None)

Optional precomputed (Q, categories) where Q is a row-stochastic (cluster x category) DataFrame and categories its column order — e.g. from mgsa_to_cluster_distribution(). When given, it is used as the seed directly and enr_res/the enrichment knobs are ignored, letting any per-cluster distribution (MGSA, enrichment, custom) drive the propagation + entropy-null resolver.

ranking_metric Literal['Adjusted P-value', 'Adjusted P-value Bonferroni', 'P-value'] (default: 'Adjusted P-value Bonferroni')

Forwarded to enrichment_to_cluster_distribution() (unused when cluster_distribution is supplied).

threshold float (default: 0.05)

Forwarded to enrichment_to_cluster_distribution() (unused when cluster_distribution is supplied).

temperature float (default: 1.0)

Forwarded to enrichment_to_cluster_distribution() (unused when cluster_distribution is supplied).

s0 float (default: 0.0)

Forwarded to enrichment_to_cluster_distribution() (unused when cluster_distribution is supplied).

s_max float (default: 300.0)

Forwarded to enrichment_to_cluster_distribution() (unused when cluster_distribution is supplied).

unknown_label str | None (default: 'unknown')

Forwarded to enrichment_to_cluster_distribution() (unused when cluster_distribution is supplied).

class_balance bool (default: True)

Forwarded to competitive_propagation().

min_probability float | None (default: None)

Forwarded to competitive_propagation().

obsp_key str (default: 'connectivities')

Forwarded to competitive_propagation().

method Literal['propagation', 'spreading'] (default: 'propagation')

Forwarded to competitive_propagation().

iterative bool (default: False)

Forwarded to competitive_propagation().

alpha float (default: 0.8)

Forwarded to competitive_propagation().

verbose bool (default: True)

Passed through to competitive_propagation().

weight_by Literal['evidence', 'odds_ratio']

seed_obsm_key str | None

seed_categories_uns_key str | None

resolve Literal['threshold', 'entropy_null']

unknown_gate float

null Literal['permutation', 'analytic'] | None

n_permutations int

alpha_fdr float

multi_label_cum float

single_eff_k float

max_labels int

min_secondary_mass float

canonical_order bool

random_state int

set_colors bool

Return type:

None

Returns:

None. data is modified in place.