liana.mt.get_lric_divergence

liana.mt.get_lric_divergence(adata=None, uns_key='lric', liana_res=None, feature_a=None, feature_b=None, max_dist=None, transform_fn=<function _log2_floor>, min_bins=3)

Compare the full g(r) profiles of two curves from lric / cross_pcf.

Where get_lric_auc() collapses each curve to a signed mean (so opposite deviations at different radii cancel), the divergence is the span-normalised area between two transform_fn(g(r)) curves – 0 means identical spatial profiles, larger means more different – and reports where along radius the separation peaks.

Parameters:

adata AnnData | None (default: None)

Annotated data object. Its .uns[uns_key] holds the result. Mutually exclusive with liana_res.

uns_key str (default: 'lric')

Key in adata.uns that contains the LIANA results. Default is 'liana_res'.

liana_res DataFrame | None (default: None)

liana_res a DataFrame in liana’s format.

A lric / cross_pcf result, used when adata is None. May be a concatenation of several results with extra annotation columns (e.g. condition) – pin those in the selections to compare the same interaction across conditions.

feature_a dict[str, object] | None (default: None)

Selection of the first curve as {column: value} over any columns of the result, e.g. dict(interaction="Dcn^Egfr") or dict(interaction="Dcn^Egfr", condition="stim"). It must resolve to a single interaction; rows it leaves unpinned (e.g. replicate samples) average into one curve per radius.

feature_b dict[str, object] | None (default: None)

Selection of the second curve; same rules as feature_a.

max_dist float | None (default: None)

Compare only over radii r < max_dist; None uses all radii.

transform_fn Callable[[NDArray[floating]], NDArray[floating]] (default: <function _log2_floor at 0x7e3fd8445c60>)

Applied to g before comparing; defaults to log2 with g floored at 0.05, so empty/depleted bins stay finite. Pass numpy.log2 for the strict behaviour where radii with a non-finite transformed curve are dropped from the comparison.

min_bins int (default: 3)

Minimum shared finite radius bins required; fewer raises a ValueError.

Return type:

Series

Returns:

A pandas.Series with divergence (mean |A - B| across radius), r_star (radius of the largest separation), delta_star (signed A - B there), direction, the selections and their display labels.

Examples

>>> import liana as li
>>> adata = li.ds.generate_toy_spatial()
>>> li.mt.cross_pcf(adata, groupby="bulk_labels", key_added="cross_pcf")
>>> div = li.mt.get_lric_divergence(
...     adata,
...     "cross_pcf",
...     feature_a=dict(source="CD14+ Monocyte", target="CD34+"),
...     feature_b=dict(source="CD14+ Monocyte", target="CD19+ B"),
... )