liana.mt.lric.__call__

lric.__call__(adata, resource=None, resource_name=None, interactions=None, groupby=None, spatial_key='spatial', max_radius=200, radius_step=20, annulus_steps=1, extend_first_annulus=True, cell_types=None, min_cells=None, groupby_pairs=None, expr_prop=0.0, complex_sep='_', lr_sep='^', transform_fn=None, use_raw=False, layer=None, pair_chunk=None, key_added='lric', inplace=True, verbose=False)

Ligand-Receptor Interaction Correlation (LRIC).

Computes an expression-weighted cross-PCF g(r): each cell’s contribution at distance r is weighted by its ligand and receptor expression, so g(r) > 1 flags ligand- and receptor-expressing cells that are spatially co-enriched beyond cell-type co-localisation alone — candidate ligand-receptor interactions that are both proximal and co-expressed.

When groupby is None (default), all cells are treated as potential senders and receivers (self-pairs excluded), providing a global screen for LR pairs with strong spatial co-enrichment signal.

When groupby is a column name in adata.obs, the LRIC is computed for every directed sender→receiver cell-type pair, and each interaction is additionally decomposed into an architecture-only (g_pcf) and an expression-only (g_expr) component.

Parameters:

adata AnnData

Annotated data object.

resource DataFrame | None (default: None)

A pandas dataframe with [ligand, receptor] columns. If provided will overrule the resource requested via resource_name

resource_name str | None (default: None)

Name of the resource to be used for ligand-receptor inference. See li.rs.show_resources() for available resources.

interactions list[tuple[str, str]] | None (default: None)

List of tuples with ligand-receptor pairs [(ligand, receptor), ...] to be used for the analysis. If passed, it will overrule the resource requested via resource and resource_name.

groupby str | None (default: None)

Column in adata.obs used to define cell types. None runs the cell-type-agnostic mode across all cells.

spatial_key str (default: 'spatial')

Key in adata.obsm that contains the spatial coordinates.

max_radius float (default: 200)

Inner edge of the last (widest) annulus bin; the outer edge extends to max_radius + annulus_steps * radius_step.

radius_step float (default: 20)

Step between successive annulus inner edges.

annulus_steps int (default: 1)

Ring width of each annulus, in units of radius_step (width = annulus_steps * radius_step). 1 (default) gives disjoint annuli that tile the range without gaps or overlap; > 1 gives overlapping annuli – a annulus_steps-wide moving window over the same tiles, i.e. a smoothed g(r).

extend_first_annulus bool (default: True)

If True (default), extend the first annulus inward to start at radius 0 (spanning [0, (1 + annulus_steps) * radius_step)) rather than at radius_step. Cell centroids cannot lie closer than ~one cell diameter, so the innermost band is otherwise a thin, near-empty, high-variance bin; extending it folds genuine cell-cell contact pairs into the first bin instead of discarding them. False keeps the first annulus at [radius_step, (1 + annulus_steps) * radius_step). In LRIC this specifically preserves juxtacrine (direct-contact) ligand-receptor signal in the first bin.

cell_types Sequence[str] | None (default: None)

Subset of cell types to consider. Defaults to all types in adata.obs[groupby]. Only relevant when groupby is set.

min_cells int | None (default: None)

Minimum cells (per cell identity if grouped by groupby) to be considered for downstream analysis. Default None derives the threshold from slide composition instead of using a fixed count: cell types making up no more than 1% of all cells are dropped.

groupby_pairs DataFrame | None (default: None)

A DataFrame with columns source and target to be used to subset the possible combinations of interacting cell types. If None, all possible combinations are used. Only relevant when groupby is set. Restricts the directed sender->receiver combinations actually computed to those listed; cell types referenced by groupby_pairs are also folded into cell_types.

expr_prop float (default: 0.0)

Minimum expression proportion for the ligands and receptors (+ their subunits) in the corresponding cell identities. Set to 0 to return unfiltered results. Computed within the relevant population: each cell type in pairwise mode, all cells in agnostic mode. Pairs below the threshold are set to NaN.

complex_sep str | None (default: '_')

Separator used to identify multi-subunit complexes in the resource (e.g. "_" splits "ITGAV_ITGB3" into its subunits and adds the minimum-subunit expression as a new column in adata.var). Set to None to skip complex handling.

lr_sep str (default: '^')

Separator to use when joining ligand and receptor names into interactions.

transform_fn Callable[[ndarray], ndarray] | None (default: None)

Expression transform applied to ligand and receptor matrices, defaulting to mean-normalisation to 1 (_linear_transform).

use_raw bool (default: False)

Whether to use the .raw attribute of adata. Defaults to False (uses .X).

layer str | None (default: None)

Layer in anndata.AnnData.layers to use. If None, use anndata.AnnData.X.

pair_chunk int | None (default: None)

Deprecated since 2.1 and ignored. The weighted numerator is now accumulated without materialising per-chunk temporaries, so there is nothing to tune.

key_added str (default: 'lric')

Key under which the results will be stored in adata.uns if inplace is True.

inplace bool (default: True)

Whether to store results in place, or else to return them.

verbose bool (default: False)

Verbosity flag.

Return type:

DataFrame | None

Returns:

A long-format pandas.DataFrame (liana’s liana_res convention) with one row per interaction x radius bin, returned if inplace=False, else None (stored in adata.uns[key_added]).

Agnostic mode columns: ligand_complex, receptor_complex, interaction ("ligand<lr_sep>receptor"), radius (the annulus’ inner edge) and g.

Pairwise mode additionally carries source / target (the sender and receiver cell types) and the g_expr / g_pcf decomposition, where g_pcf is shared by all LR pairs of a given source ->``target``.

expr_prop-masked interactions are kept as NaN rows.

Examples

Cell-type-agnostic LRIC across all cells:

>>> import liana as li
>>> adata = li.ds.generate_toy_spatial()
>>> li.mt.lric(adata, resource_name="consensus", key_added="lric")
>>> list(adata.uns["lric"].columns)
['ligand_complex', 'receptor_complex', 'interaction', 'radius', 'g']

The cell-type pairwise variant additionally decomposes each interaction into architecture (g_pcf) and expression (g_expr) components:

>>> adata.obs["cell_type"] = adata.obs["bulk_labels"]
>>> li.mt.lric(adata, resource_name="consensus", groupby="cell_type", key_added="lric_ct")

Rank the interactions with liana.mt.get_lric_auc() – its output feeds straight into liana.pl.dotplot() – and draw a single g(r) profile with liana.pl.lric_lineplot().