cassiopeia.tl.compute_evolutionary_coupling#
- cassiopeia.tl.compute_evolutionary_coupling(tree, meta_variable, minimum_proportion=0.05, number_of_shuffles=500, random_state=None, dissimilarity_map=None, cluster_comparison_function=CPUDispatcher(<function net_relatedness_index>), **comparison_kwargs)[source]#
Computes Evolutionary Coupling of categorical variables.
Using the methodology described in Yang, Jones et al, BioRxiv (2021), this function will compute the “evolutionary coupling” statistic between values that a categorical variable can take on with the tree. For example, this categorical variable can be a “cell type”, and this function will compute the evolutionary couplings between all types of cell types. This indicates how closely related these cell types are to one another.
Briefly, this statistic is the Z-normalized mean distance between categories in the specified categorical variable. Note that empirical nulls that have a standard deviation of 0 lead to NaNs in the resulting evolutionary coupling matrix.
The computational complexity of this function is O(n^2 log n + (B+1)(K^2 * O(distance_function)) for a tree with n leaves, a variable with K categories, and B random shuffles.
- Parameters:
- tree
CassiopeiaTree CassiopeiaTree
- meta_variable
str Column in tree.cell_meta that stores a categorical variable with K categories.
- minimum_proportion
float(default:0.05) Minimum proportion of cells that a category needs to appear in to be considered.
- number_of_shuffles
int(default:500) Number of times to shuffle the data to compute the empirical Z score.
- random_state
Optional[RandomState] (default:None) Numpy random state to parameterize the shuffling.
- dissimilarity_map
Optional[DataFrame] (default:None) A precomputed dissimilarity map between all leaves.
- cluster_comparison_function
Callable(default:CPUDispatcher(<function net_relatedness_index at 0x7ff8808a70d0>)) A function for comparing the mean distance between groups. By default, this is the Net Relatedness Index.
- **comparison_kwargs
Extra arguments to pass to the cluster comparison function.
- tree
- Return type:
- Returns:
A K x K evolutionary coupling dataframe.