solver_utilities.py
High-level description
This file provides utility functions for the solver module in Cassiopeia. These functions are used for tasks such as generating unique node names, collapsing unifurcations in a tree, transforming prior probabilities into weights, and converting sample names to indices.
Code Structure
The file contains several independent functions that are used by other modules in the solver package. These functions are not directly interconnected but serve as helper functions for various solver algorithms.
References
This file references the ete3, numpy, pandas, and time libraries. It also references the PriorTransformationError exception from the cassiopeia.mixins module.
Symbols
node_name_generator
Description
This function creates a generator that yields unique node names by hashing timestamps. This is used to ensure that each node in the reconstructed tree has a unique identifier.
Inputs
None
Outputs
| Name | Type | Description |
|---|---|---|
| generator | Generator[str, None, None] | A generator object that yields unique node names |
Internal Logic
The function uses the blake2b hash function from the hashlib library to generate a 12-byte hash of the current timestamp. This hash is then converted to a hexadecimal string and appended to the prefix “cassiopeia_internal_node” to create a unique node name.
collapse_unifurcations
Description
This function collapses all unifurcations in a given ete3.Tree. Unifurcations are nodes with only one child. Collapsing them simplifies the tree structure by removing unnecessary nodes.
Inputs
| Name | Type | Description |
|---|---|---|
| tree | ete3.Tree | The tree to collapse unifurcations in |
Outputs
| Name | Type | Description |
|---|---|---|
| collapsed_tree | ete3.Tree | A copy of the input tree with all unifurcations collapsed |
Internal Logic
The function iterates through all nodes in the tree and identifies those with only one child. For each unifurcation, it removes the node and connects its child directly to its parent.
transform_priors
Description
This function transforms prior probabilities into weights for use in greedy solver algorithms. It supports three transformations: negative log, inverse, and square root inverse.
Inputs
| Name | Type | Description |
|---|---|---|
| priors | Optional[Dict[int, Dict[int, float]]] | A dictionary of prior probabilities for each character/state pair |
| prior_transformation | str | The transformation to apply to the priors. Defaults to “negative_log” |
Outputs
| Name | Type | Description |
|---|---|---|
| weights | Dict[int, Dict[int, float]] | A dictionary of weights for each character/state pair |
Internal Logic
The function first checks if the specified transformation is supported. Then, it applies the chosen transformation to each prior probability and stores the resulting weight in a new dictionary.
convert_sample_names_to_indices
Description
This function maps sample names to their corresponding integer indices in a given list of names. This is used for efficient indexing operations in the solver algorithms.
Inputs
| Name | Type | Description |
|---|---|---|
| names | List[str] | A list of sample names |
| samples | List[str] | A subset of sample names to be mapped to indices |
Outputs
| Name | Type | Description |
|---|---|---|
| indices | List[int] | A list of integer indices corresponding to the input samples |
Internal Logic
The function creates a dictionary mapping each sample name to its index in the names list. Then, it uses this dictionary to map the input samples to their corresponding indices.
save_dissimilarity_as_phylip
Description
This function saves a dissimilarity map as a PHYLIP file. The PHYLIP format is a standard format for representing phylogenetic trees and distance matrices.
Inputs
| Name | Type | Description |
|---|---|---|
| dissimilarity_map | pd.DataFrame | A dissimilarity map |
| path | str | The path to save the PHYLIP file |
Outputs
None
Internal Logic
The function converts the dissimilarity map to a NumPy array and writes it to a file in the PHYLIP format. The file includes the number of samples and a lower triangular matrix of dissimilarities.