liana.mt.bivariate.__call__

bivariate.__call__(mdata, local_name='cosine', global_name=None, resource_name=None, resource=None, interactions=None, connectivity_key='spatial_connectivities', mask_negatives=False, add_categories=False, n_perms=None, seed=1337, nz_prop=0.05, remove_self_interactions=True, complex_sep='_', xy_sep='^', verbose=False, **kwargs)

A method for bivariate local spatial metrics.

Parameters:

mdata MuData | AnnData

MuData (multimodal) data object.

local_name str | None (default: 'cosine')

Name of the local function to use for the analysis. Passing None will return only the Global scores.

global_name str | list[str] | None (default: None)

Name or names (list) of the global function(s) to use for the analysis. Passing None will not calculate any global scores

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.

resource DataFrame | None (default: None)

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

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.

connectivity_key str (default: 'spatial_connectivities')

Key in adata.obsp that contains the spatial connectivity matrix. Default is 'spatial_connectivities'.

mask_negatives bool (default: False)

Whether to mask negative-negative (low-low) or uncategorized interactions.

add_categories bool (default: False)

Whether to add categories about the local scores.

n_perms int | None (default: None)

Number of permutations for the permutation test. If None, no p-values are computed.

seed int (default: 1337)

Random seed for reproducibility.

nz_prop float (default: 0.05)

Minimum proportion of non-zero values for each features. For example, if working with gene expression data, this would be the proportion of cells expressing a gene. Both features must have a proportion greater than nz_prop to be considered in the analysis.

remove_self_interactions bool (default: True)

Whether to remove self-interactions. True by default.

complex_sep None | str (default: '_')

Separator to use for complex names.

xy_sep str (default: '^')

Separator to use for interaction names.

verbose bool (default: False)

Verbosity flag.

**kwargs Any

Additional keyword arguments.

For an AnnData input:

x_name

Name of the x-variable. If passing a resource dataframe, this should match the first column. By default: ‘ligand’.

y_name

Name of the y-variable. If passing a resource dataframe, this should match the second column. By default: ‘receptor’.

For a MuData input:

x_mod

Name of the modality to use for the x-axis.

y_mod

Name of the modality to use for the y-axis.

x_name

Name of the x-variable. If passing a resource dataframe, this should match the first column. By default: ‘x’.

y_name

Name of the y-variable. If passing a resource dataframe, this should match the second column. By default: ‘y’.

x_use_raw: bool

Whether to use the raw counts for the x-mod.

y_use_raw: bool

Whether to use the raw counts for y-mod.

x_layer: str

Layer to use for x-mod.

y_layer: str

Layer to use for y-mod.

x_transform: bool

Function to transform the x-mod.

y_transform: bool

Function to transform the y-mod.

Raises:

ValueError – If n_perms is not None or negative or if mdata is not a valid type.

Return type:

AnnData | DataFrame | None

Returns:

An AnnData object, (optionally) with multiple layers which correspond categories/p-values, and the actual scores are stored in .X. Moreover, global stats are stored in .var.

Examples

Relates each ligand to its receptor at every spot, given the spatial connectivities of liana.pp.spatial_neighbors():

>>> import liana as li
>>> adata = li.ds.generate_toy_spatial()
>>> lrdata = li.mt.bivariate(
...     adata, resource_name="consensus", local_name="morans", global_name="morans", n_perms=0
... )

One column per ligand-receptor pair that passed the expression filters, named 'ligand^receptor'. n_perms=0 uses the analytical p-values available for Moran’s R – a positive integer runs that many permutations instead, None skips them.

li.mt.bivariate.show_functions() lists the available local_name choices. Pass a MuData with x_mod/y_mod instead of an AnnData to relate two modalities.