cospar.tl.fate_coupling

cospar.tl.fate_coupling(adata, selected_fates=None, source='transition_map', selected_times=None, fate_map_method='sum', method='SW', normalize=True, silence=False, ignore_cell_number=False, fate_normalize_source='X_clone', select_clones_with_fates=None, select_clones_without_fates=None, select_clones_mode='or', normalized_X_similarity=False, **kwargs)

Compute fate coupling determined by the transition map.

We use the fate map \(P_i(\mathcal{C}_l)\) towards a set of fate clusters \(\{\mathcal{C}_l, l=0,1,2...\}\) to compute the fate coupling \(Y_{ll'}\).

  • If method=’SW’: we first obtain \(Y_{ll'}=\sum_i P_i(\mathcal{C}_l)P_i(\mathcal{C}_{l'})\). Then, we normalize the the coupling: \(Y_{ll'}\leftarrow Y_{ll'}/\sqrt{Y_{ll}Y_{l'l'}}\).

  • If method=’Weinreb’, we calculate the normalized covariance as in get_normalized_covariance()

Parameters
adata : AnnData object

Assume to contain transition maps at adata.uns.

selected_fates : list, optional (default: all fates)

List of cluster ids consistent with adata.obs[‘state_info’]. It allows a nested list, where we merge clusters within each sub-list into a mega-fate cluster.

source : str, optional (default: ‘transition_map’)

Choices: {‘X_clone’, ‘transition_map’, ‘intraclone_transition_map’,…}. If set to be ‘clone’, use only the clonal information. If set to be any of the precomputed transition map, use the transition map to compute the fate coupling. The actual available map depends on adata itself, which can be accessed at adata.uns[‘available_map’]

selected_times : list, optional (default: all)

A list of time points to further restrict the cell states to plot. The default choice is not to constrain the cell states to show.

fate_map_method : str, optional (default: ‘sum’)

Method to obtain the fate probability map \(P_i(\mathcal{C})\) towards a set of states annotated with fate \(\mathcal{C}\). Available options: {‘sum’, ‘norm-sum’}. See fate_map().

method : str, optional (default: ‘SW’)

Method to normalize the coupling matrix: {‘SW’, ‘Weinreb’,’Jaccard’}.

normalize

We normalize the count matrix first within each cluster, then, within each clone separately for each time point. This was set to be off in the original CoSpar publication.

silence

Suppress information printing.

ignore_cell_number : bool

Ignore the cell number of a clone within a cluster. i.e., binarize a clone’s contribution towards a cluster. This only works when ‘source=X_clone’ This biases towards large clusters, which will host many clones (most of them just a few cells)

fate_normalize_source

Source for cluster-wise normalization: {‘X_clone’,’state_info’}. ‘X_clone’: directly row-normalize coarse_X_clone; ‘state_info’: compute each cluster size directly, and then normalize coarse_X_clone. The latter method is useful if we have single-cell resolution for each fate.

select_clones_with_fates : list = None,

Select clones that labels fates from this list.

select_clones_without_fates : list = None,

Exclude clones that labels fates from this list.

select_clones_mode : str = {'or','and'}

Logic rule for selection.

Returns

  • X_coupling and the corresponding fate_names index are stored as a dictionary

  • at adata.uns[f”fate_coupling_{source}”]={“X_coupling” (X_coupling, ‘fate_names’: fate_names})