liana.method.bivariate.__call__

liana.method.bivariate.__call__#

bivariate.__call__(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 (None | str | list[str] (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 (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[str] (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 (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 –

    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.utils.spatial_neighbors():

>>> import liana as li
>>> adata = li.testing.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.