liana.utils.get_variable_loadings

liana.utils.get_variable_loadings#

liana.utils.get_variable_loadings(adata=None, varm_key=None, view_sep=None, variable_sep=None, pair_sep=None, var_names=None, pair_names=None, drop_columns=True, loadings=None)#

Extract variable loadings from an AnnData object.

Parameters:

  • adata (AnnData | MuData (default: None)) – Annotated data object.

  • varm_key (str (default: None)) – Key to use when extracting variable loadings from mdata.varm. Ignored when loadings is provided.

  • view_sep (str | None (default: None)) – Separator to use when splitting view:variable names into view and variable

  • variable_sep (str | None (default: None)) – Separator to use when splitting variable names into var_names

  • pair_sep (str | None (default: None)) – Separator to use when splitting view names into pair_names

  • var_names (list (default: None)) – Variable names given to the splitted variable (‘ligand_complex’ and ‘receptor_complex’ by default)

  • pair_names (list (default: None)) – Variable names given to the splitted pair (‘source’ and ‘target’ by default)

  • drop_columns (bool (default: True)) – If True, drop the view:variable column

  • loadings (DataFrame | dict | None (default: None)) – Pre-extracted loadings to use instead of reading from adata.varm. Either a features-by-factors DataFrame, or a dict of per-view features-by-factors DataFrames (e.g. the output of a MOFA-Flex model’s get_weights()), which is concatenated feature-wise. When provided, adata and varm_key are ignored and the existing factor column names are preserved.

Return type:

DataFrame

Returns:

Returns a pandas DataFrame with the variable loadings for the specified index.

Raises:

ValueError – If varm_key not found in .varm (when loadings is not provided)

Examples

varm_key points at the feature by factor matrix written by a factorization model – here liana.multi.nmf() on the local scores of liana.method.bivariate, whose var_names are 'ligand^receptor':

>>> import liana as li
>>> adata = li.testing.generate_toy_spatial()
>>> lrdata = li.mt.bivariate(adata, resource_name='consensus',
...                          local_name='cosine', global_name=None,
...                          n_perms=None)
>>> li.multi.nmf(lrdata, n_components=3, random_state=0)
>>> loadings = li.ut.get_variable_loadings(lrdata, varm_key='NMF_H',
...                                        variable_sep='^')

The separators split those composite names back into their parts, and the rows are ordered by the absolute loading on the first factor:

>>> loadings.head(3).round(3)
  ligand_complex receptor_complex  Factor1  Factor2  Factor3
6       HLA-DPB1              CD4    2.518      0.0    0.114
4       HLA-DQB1              CD4    2.498      0.0    0.034
0        HLA-DRA              CD4    2.486      0.0    0.160

Views built by liana.multi.lrs_to_views() name their variables 'source&target:ligand^receptor', which view_sep=':', variable_sep='^' and pair_sep='&' split in the same way.