cassiopeia/tools/topology.py:
High-level description
This file contains utility functions to assess topological properties of phylogenetic trees, specifically focusing on balance and expansion. It provides methods to compute expansion p-values and cophenetic correlation for CassiopeiaTree objects.Code Structure
The main functions in this file arecompute_expansion_pvalues and compute_cophenetic_correlation. These functions operate on CassiopeiaTree objects and utilize various helper functions and statistical methods to analyze tree topology.
Symbols
compute_expansion_pvalues
Description
This function calculates expansion p-values for nodes in a phylogenetic tree, assessing the probability of observing a given subclade size under a neutral coalescent model.Inputs
Outputs
Internal Logic
- Initializes attributes for each node in the tree
- Traverses the tree in depth-first order
- For each node, calculates the expansion p-value based on the number of leaves in its subtree
- Adds the calculated p-values as attributes to the tree nodes
Performance Considerations
The function runs in O(n log n) time for balanced trees, but can be up to O(n^3) for highly unbalanced trees.compute_cophenetic_correlation
Description
Computes the cophenetic correlation of a lineage, which is the Pearson correlation between the phylogenetic distance and character dissimilarity.Inputs
Outputs
Internal Logic
- Computes or uses provided phylogenetic weight matrix and dissimilarity map
- Aligns matrices to ensure they correspond to the same set of leaves
- Converts matrices to condensed distance matrices
- Calculates Pearson correlation between phylogenetic distances and dissimilarities
Performance Considerations
If weights and dissimilarity map are not precomputed, the function runs in O(mn^2 + n^2logn + n^2) time, where n is the number of leaves and m is the number of characters.simple_coalescent_probability
Description
Computes the probability of observing a given number of samples in a lineage under a simple coalescent model.Inputs
Outputs
nCk
Description
Computes the binomial coefficient (n choose k).Inputs
Outputs
Dependencies
- numpy
- pandas
- scipy
- cassiopeia.data
- cassiopeia.mixins
- cassiopeia.solver.dissimilarity_functions
Error Handling
The code uses custom exceptions fromcassiopeia.mixins to handle errors specific to CassiopeiaTree operations.