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', min_probability=0.5, min_term_size=0, eta=1.0, tau=0.4, maxk=3, cap=12, cv_splits=5, n_probe=96, seed=0, key_added='ann_diffusion', copy=False, verbose=False)

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_propagation() 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").

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}_resolved]: "likelihood" (default; containment-link active set), "specific" (most-specific term with P >= min_probability), "argmax", or None to skip and only write probabilities.

min_probability float (default: 0.5)

Threshold for the "specific" resolver and for the compact multi-label set.

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.

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.

seed 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").

copy bool (default: False)

If True operate on and return a copy; otherwise annotate in place and return None.

verbose bool (default: False)

Print progress.

Return type:

AnnData | None

Returns:

Writes obsm[{key_added}_probabilities] (per-term calibrated membership, non-simplex), uns[{key_added}_categories], uns[{key_added}_alpha] (per-term a*), obs[{key_added}_maxp] (top-call confidence), and — when resolve is set — obs[{key_added}_resolved] and obs[{key_added}_resolved_label_compact]. Returns the AnnData if copy=True, else None.