grassp.tl.independent_diffusion

grassp.tl.independent_diffusion#

independent_diffusion(data, gene_sets, gene_key='gene_symbol', species='hsap', obsp_key='connectivities', alphas=None, calibration='size_aware', kappa=30.0, resolve='likelihood', term_threshold=0.5, min_term_size=0, eta=1.0, tau=0.4, maxk=3, cap=12, nest_threshold=0.8, cv_splits=5, n_probe=96, random_state=0, key_added='ann_diffusion', inplace=True, verbose=False)[source]#

Annotate a map with overlapping / hierarchical labels by one-vs-rest diffusion.

Each term in gene_sets is diffused independently over the kNN graph (no cross-term competition), giving a non-simplex per-term membership probability. See the module docstring for the full pipeline. For mutually-exclusive single labels (e.g. markers), use competitive_diffusion() instead.

Parameters:
data AnnData

AnnData with a neighbour graph in obsp[obsp_key].

gene_sets

The label vocabulary: a {term: [gene_ids]} dict, a path to a .gmt file, or an Enrichr library name (fetched via gseapy).

gene_key str (default: 'gene_symbol')

obs column with the gene identifiers matching gene_sets (default "gene_symbol"). When several entries share an identifier (isoforms, duplicate accessions), only the first carries the gene’s annotation and the others are scored as unannotated proteins, so one gene is one unit of evidence and a protein cannot vouch for itself through a duplicate; the count is recorded in uns[{key_added}_params]["duplicate_gene_entries"].

species str (default: 'hsap')

Species tag passed to the GMT loader when gene_sets is a path/name.

obsp_key str (default: 'connectivities')

Neighbour-graph key in obsp (default "connectivities").

alphas default: None

Candidate diffusion depths; the per-term optimum a* is chosen by leave-one-out average precision. Default np.linspace(0.1, 0.9, 19).

calibration Literal['size_aware', 'shrunk', 'pooled', 'per_term', 'none'] (default: 'size_aware')

Score→probability calibration (default "size_aware"). See module docstring; "none" returns the raw honest score.

kappa float (default: 30.0)

Support-weight prior for "size_aware"/"shrunk" blending (w = m/(m+kappa)).

resolve Optional[Literal['likelihood', 'specific', 'argmax']] (default: 'likelihood')

How to turn the probability vector into obs[{key_added}]: "likelihood" (default; containment-link active set), "specific" (most-specific term with P >= term_threshold), "argmax", or None to skip and only write probabilities.

term_threshold float (default: 0.5)

Per-term membership threshold: a term is a candidate for a protein when its calibrated membership is at least this. Used by the "specific" resolver and for the compact multi-label set. Deliberately not called min_probability – that name means “abstain below this confidence” everywhere else in grassp, which is a different question from “does this protein belong to this term”.

min_term_size int (default: 0)

Granularity floor: a protein may only be labelled with a term that has at least this many members present in the map. Because the vocabulary is hierarchical, an under-represented term is dropped in favour of its larger ancestor (which still explains the neighbourhood by containment), so raising it yields fewer, better- supported labels without abstaining. 0 (default) applies no floor.

eta float (default: 1.0)

Likelihood-resolver parameters: term penalty, candidate floor, max active-set size, and candidate cap.

tau float (default: 0.4)

Likelihood-resolver parameters: term penalty, candidate floor, max active-set size, and candidate cap.

maxk int (default: 3)

Likelihood-resolver parameters: term penalty, candidate floor, max active-set size, and candidate cap.

cap int (default: 12)

Likelihood-resolver parameters: term penalty, candidate floor, max active-set size, and candidate cap.

nest_threshold float (default: 0.8)

Term a is nested in b when |G_a & G_b| / |G_a| >= nest_threshold over the genes present in the map; only nested terms explain each other in the "likelihood" resolver, and the multi-location call lists the called terms that contain no other called term. Real vocabularies put nested pairs at 0.95-1.0 and co-annotated ones (e.g. nucleus / cytoplasm) at <= 0.77.

cv_splits int (default: 5)

Cross-fit folds, Hutchinson probes for n_eff, and RNG seed.

n_probe int (default: 96)

Cross-fit folds, Hutchinson probes for n_eff, and RNG seed.

random_state int (default: 0)

Cross-fit folds, Hutchinson probes for n_eff, and RNG seed.

key_added str (default: 'ann_diffusion')

Prefix for the outputs (default "ann_diffusion").

inplace bool (default: True)

If True (default) annotate data and return None; otherwise operate on and return a copy. Named to match every other annotator – this was the one that spelled it copy, inverted.

verbose bool (default: False)

Print progress.

Return type:

AnnData | None

Returns:

Writes obsm[{key_added}_probabilities] (per-term calibrated membership, non-simplex, with the term names as its columns), uns[{key_added}_alpha] (per-term a*), obs[{key_added}_probability] (top membership), uns[{key_added}_params] (provenance, including kind="per_term"), and — when resolve is set — obs[{key_added}] (the resolved call) and obs[{key_added}_label_compact] (the multi-location call: the called terms that contain no other called term, most probable first, joined by the shared separator). Returns the AnnData if inplace=False, else None.