High-level description
The code defines aForest class in Python, representing a collection of phylogenetic trees. It provides functionalities for loading, generating, manipulating, analyzing, and saving these tree collections. This includes methods for calculating various phylogenetic statistics, annotating tree nodes with features, and visualizing the trees.
Code Structure
TheForest class is the main component, containing methods for manipulating collections of Tree objects. The Tree class (defined in a separate file) represents a single phylogenetic tree and provides methods for manipulating and analyzing individual trees. The Forest class leverages the functionalities of the Tree class to operate on entire collections of trees.
References
jungle.tree.Tree: TheForestclass heavily relies on theTreeclass for individual tree operations.
Symbols
Symbol Name: Forest
Description:
This class represents a collection of phylogenetic trees and provides methods for their manipulation and analysis.Inputs:
Outputs:
The class itself is the output, representing aForest object.
Internal Logic:
The class stores the trees in a list and provides methods for:- Loading trees from various formats (Newick, pickle, tar.gz).
- Generating trees.
- Concatenating forests.
- Annotating nodes with features.
- Calculating phylogenetic statistics.
- Fitting models to distributions of metrics.
- Visualizing trees.
- Saving the forest to disk.
Symbol Name: from_newick
Description:
Class method to construct aForest object by loading trees from Newick files.
Inputs:
Outputs:
Internal Logic:
The method iterates through the provided filenames, creates aTree object for each file using Tree.from_newick, and appends it to the trees list of the Forest object.
Symbol Name: from_pickle
Description:
Class method to load aForest object from a pickle file.
Inputs:
Outputs:
Internal Logic:
The method opens the pickle file, optionally gzipped, and loads theForest object using pickle.load.
Symbol Name: generate
Description:
Class method to generate aForest object by simulating trees.
Inputs:
Outputs:
Internal Logic:
The method generatesn_trees number of trees using Tree.generate and appends them to the trees list of the Forest object.
Symbol Name: from_newick_tar_gz
Description:
Class method to load aForest object from a gzipped tar archive of Newick files.
Inputs:
Outputs:
Internal Logic:
The method opens the tar.gz file, iterates through its members, extracts the content of each Newick file, creates aTree object using Tree.from_newick, and appends it to the trees list of the Forest object.
Symbol Name: to_newick
Description:
Writes the trees in theForest object to a gzipped tar archive of Newick files.
Inputs:
Outputs:
This method doesn’t return any value. It writes the trees to the specified file.Internal Logic:
The method iterates through the trees, writes each tree to a temporary Newick file usingTree.to_newick, adds all temporary files to a tar.gz archive, and finally deletes the temporary files.
Symbol Name: concat
Description:
Concatenates twoForest objects into a new one.
Inputs:
Outputs:
Internal Logic:
The method combines thetrees lists of both forests, concatenates other list-like attributes using _concat_lists_safe, and creates a new Forest object with the combined data.
Symbol Name: annotate_standard_node_features
Description:
Annotates each node of each tree in the forest with standard features: depth, depth_rank, num_children, num_descendants.Inputs:
This method doesn’t take any input arguments.Outputs:
This method doesn’t return any value. It modifies the trees in place.Internal Logic:
The method iterates through the trees and calls theannotate_standard_node_features method of each Tree object.
Symbol Name: annotate_imbalance
Description:
Annotates each node of each tree in the forest with its imbalance (I), calculated as the maximum number of descendants among its children divided by the total number of descendants.Inputs:
This method doesn’t take any input arguments.Outputs:
This method doesn’t return any value. It modifies the trees in place.Internal Logic:
The method iterates through the trees and calls theannotate_imbalance method of each Tree object.
Symbol Name: annotate_colless
Description:
Annotates each node of each tree in the forest with its Colless index.Inputs:
This method doesn’t take any input arguments.Outputs:
This method doesn’t return any value. It modifies the trees in place.Internal Logic:
The method iterates through the trees and calls theannotate_colless method of each Tree object.
Symbol Name: node_features
Description:
Returns a Pandas DataFrame containing features for each node of each tree in the forest.Inputs:
Outputs:
Internal Logic:
The method retrieves the node features from each tree usingTree.node_features, concatenates them into a single DataFrame, and ensures unique tree names.
Symbol Name: rescale
Description:
Rescales all trees in the forest to have a specific total branch length.Inputs:
Outputs:
This method doesn’t return any value. It modifies the trees in place.Internal Logic:
The method iterates through the trees and calls therescale method of each Tree object with the specified total_branch_length.
Symbol Name: resolve_polytomy
Description:
Resolves all polytomies (nodes with more than two children) in each tree by creating an arbitrary dichotomous structure.Inputs:
This method doesn’t take any input arguments.Outputs:
This method doesn’t return any value. It modifies the trees in place.Internal Logic:
The method iterates through the trees and calls theresolve_polytomy method of each Tree object.
Symbol Name: site_frequency_spectrum
Description:
Calculates the site frequency spectrum (SFS) for each tree in the forest.Inputs:
This method doesn’t take any input arguments.Outputs:
Internal Logic:
The method iterates through the trees, calculates the SFS for each tree usingTree.site_frequency_spectrum, and stores them in a list.
Symbol Name: bin_site_frequency_spectrum
Description:
Calculates the binned site frequency spectrum (SFS) for each tree in the forest.Inputs:
Outputs:
Internal Logic:
The method iterates through the trees, calculates the binned SFS for each tree usingTree.bin_site_frequency_spectrum, and stores them in a list.
Symbol Name: mean_site_frequency_spectrum
Description:
Calculates the mean and standard error of the mean (SEM) of the site frequency spectrum (SFS) across all trees in the forest.Inputs:
Outputs:
Internal Logic:
The method extracts the specified SFS representation from each tree, calculates the mean and SEM across all trees usingnp.nanmean and scipy.stats.sem, and returns the results.
Symbol Name: fay_and_wus_H
Description:
Calculates Fay and Wu’s H statistic for each tree in the forest.Inputs:
This method doesn’t take any input arguments.Outputs:
Internal Logic:
The method iterates through the trees, calculates Fay and Wu’s H for each tree usingTree.fay_and_wus_H, and stores them in a list.
Symbol Name: zengs_E
Description:
Calculates Zeng’s E statistic for each tree in the forest.Inputs:
This method doesn’t take any input arguments.Outputs:
Internal Logic:
The method iterates through the trees, calculates Zeng’s E for each tree usingTree.zengs_E, and stores them in a list.