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_setsis 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), usecompetitive_diffusion()instead.- Parameters:
- data
AnnData AnnDatawith a neighbour graph inobsp[obsp_key].- gene_sets
The label vocabulary: a
{term: [gene_ids]}dict, a path to a.gmtfile, or an Enrichr library name (fetched viagseapy).- gene_key
str(default:'gene_symbol') obscolumn with the gene identifiers matchinggene_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 inuns[{key_added}_params]["duplicate_gene_entries"].- species
str(default:'hsap') Species tag passed to the GMT loader when
gene_setsis 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. Defaultnp.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 withP >= term_threshold),"argmax", orNoneto 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 calledmin_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
ais nested inbwhen|G_a & G_b| / |G_a| >= nest_thresholdover 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) annotatedataand returnNone; otherwise operate on and return a copy. Named to match every other annotator – this was the one that spelled itcopy, inverted.- verbose
bool(default:False) Print progress.
- data
- Return type:
- Returns:
Writes
obsm[{key_added}_probabilities](per-term calibrated membership, non-simplex, with the term names as its columns),uns[{key_added}_alpha](per-terma*),obs[{key_added}_probability](top membership),uns[{key_added}_params](provenance, includingkind="per_term"), and — whenresolveis set —obs[{key_added}](the resolved call) andobs[{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 ifinplace=False, elseNone.