metachat.tl.metabolic_communication

metachat.tl.metabolic_communication(adata, database_name=None, df_metasen=None, LRC_type=None, dis_thr=None, cost_scale=None, cost_type='euc', fot_eps_p=0.25, fot_eps_mu=None, fot_eps_nu=None, fot_rho=0.1, fot_nitermax=10000, fot_weights=(1.0, 0.0, 0.0, 0.0), copy=False)

Infer spatial metabolic cell communication (MCC) using the Flow Optimal Transport (FOT) framework.

Parameters

adataanndata.AnnData

The data matrix of shape n_obs × n_var (cells/spots × genes). Rows correspond to cells or spots and columns to genes.

database_namestr

Name of the metabolite–sensor interaction database (used as prefix for storing results).

df_metasenpd.DataFrame

DataFrame describing metabolite–sensor pairs, typically from MetaChatDB or related sources. Must include columns: ['HMDB.ID', 'Sensor.Gene', 'Metabolite.Pathway', 'Sensor.Pathway', 'Metabolite.Names', 'Long.Range.Channel'].

LRC_typelist of str, optional

Names of long-range channels (LRCs) such as ["Blood"], ["CSF"] or ["Blood", "CSF"].

dis_thrfloat

Distance threshold for defining the region influenced by each LRC.

cost_scaledict, optional

Weight coefficients of the cost matrix for each metabolite-sensor pair, e.g. cost_scale[(‘metA’,’senA’)] specifies weight for the pair metA and senA. If None, all pairs have the same weight.

cost_typestr, {‘euc’, ‘euc_square’}, default=’euc’

Defines how spatial distances are used as cost matrix.

fot_eps_pfloat, default=2.5e-1

The coefficient of entropy regularization for transport plan.

fot_eps_mufloat, optional

The coefficient of entropy regularization for untransported source (metabolite). Set to equal to fot_eps_p for fast algorithm.

fot_eps_nufloat, optional

The coefficient of entropy regularization for unfulfilled target (sensor). Set to equal to fot_eps_p for fast algorithm.

fot_rhofloat, optional

The coefficient of penalty for unmatched mass.

fot_nitermaxint, default=10000

Maximum iteration for flow optimal transport algorithm.

fot_weightstuple of float, default=(1.0, 0.0, 0.0, 0.0)

A tuple of four weights that add up to one. The weights corresponds to four setups of flow optimal transport: 1) all metabolite-all sensors, 2) each metabolite-all sensors, 3) all metabolite-each sensor, 4) each metabolite-each sensor.

copybool, default=False

Whether to return a new AnnData object or modify in place.

Returns

adataanndata.AnnData or None

Updates the following fields: - .obsp['MetaChat-{database}-sender-{met}-{sen}'] : n_obs × n_obs sparse matrix of sender signals. - .obsp['MetaChat-{database}-receiver-{met}-{sen}'] : n_obs × n_obs sparse matrix of receiver signals. - .obsm['MetaChat-{database}-sum-sender'] : DataFrame of per-cell sender signal sums. - .obsm['MetaChat-{database}-sum-receiver'] : DataFrame of per-cell receiver signal sums. - .uns['MetaChat-{database}-info'] : metadata including distance threshold. If copy=True, return a modified copy of adata; otherwise return None.