tessl/pypi-ete3
A Python Environment for (phylogenetic) Tree Exploration
—
Pending
core-tree.mddocs/
Core Tree Operations
Fundamental tree structure manipulation and analysis operations that form the foundation of all ETE3 functionality. These operations provide the essential capabilities for creating, modifying, traversing, and analyzing hierarchical tree structures.
Capabilities
Tree Creation and Initialization
Create tree structures from various input formats, with support for Newick format parsing and manual tree construction.
class Tree:
def __init__(self, newick=None, format=0, dist=None, support=None, name=None, quoted_node_names=False):
"""
Initialize a Tree/TreeNode instance.
Parameters:
- newick (str): Newick format string or file path
- format (int): Newick subformat (0-9)
0: flexible with support values
1: flexible with internal node names
2: all branches + leaf names + internal supports
3: all branches + all names
4: leaf branches + leaf names
5: internal and leaf branches + leaf names
6: internal branches + leaf names
7: leaf branches + all names
8: all names
9: leaf names
- dist (float): Initial branch length
- support (float): Initial support value
- name (str): Initial node name
- quoted_node_names (bool): Handle quoted node names
"""Node Structure Manipulation
Add, remove, and modify tree nodes to build and reshape tree structures.
def add_child(self, child=None, name=None, dist=None, support=None):
"""
Add a child node to current node.
Parameters:
- child (TreeNode): Existing node to add as child
- name (str): Name for new child node
- dist (float): Branch length to child
- support (float): Support value for branch
Returns:
TreeNode: The added child node
"""
def add_sister(self, sister=None, name=None, dist=None):
"""
Add a sister node at the same level.
Parameters:
- sister (TreeNode): Existing node to add as sister
- name (str): Name for new sister node
- dist (float): Branch length to sister
Returns:
TreeNode: The added sister node
"""
def remove_child(self, child):
"""
Remove a child node.
Parameters:
- child (TreeNode): Child node to remove
"""
def delete(self, prevent_nondicotomic=True, preserve_branch_length=False):
"""
Delete current node from tree.
Parameters:
- prevent_nondicotomic (bool): Avoid creating multifurcations
- preserve_branch_length (bool): Preserve branch lengths when deleting
"""
def detach(self):
"""
Detach node from its parent, returning the detached subtree.
Returns:
TreeNode: The detached node/subtree
"""Tree Traversal and Access
Navigate through tree structures using different traversal strategies and access specific nodes.
def traverse(self, strategy="levelorder", is_leaf_fn=None):
"""
Iterate over tree nodes using specified strategy.
Parameters:
- strategy (str): Traversal strategy ("preorder", "postorder", "levelorder")
- is_leaf_fn (function): Custom function to determine leaf nodes
Yields:
TreeNode: Each node in traversal order
"""
def get_leaves(self, is_leaf_fn=None):
"""
Get all leaf nodes.
Parameters:
- is_leaf_fn (function): Custom function to determine leaf status
Returns:
list: List of leaf TreeNode objects
"""
def get_descendants(self, strategy="levelorder"):
"""
Get all descendant nodes.
Parameters:
- strategy (str): Traversal strategy
Returns:
list: List of descendant TreeNode objects
"""
def get_ancestors(self):
"""
Get all ancestor nodes from current node to root.
Returns:
list: List of ancestor TreeNode objects
"""
def get_common_ancestor(self, *target_nodes):
"""
Find most recent common ancestor of target nodes.
Parameters:
- target_nodes: Variable number of TreeNode objects
Returns:
TreeNode: Common ancestor node
"""
def get_sisters(self):
"""
Get sister nodes (same parent, excluding self).
Returns:
list: List of sister TreeNode objects
"""Node Properties and Attributes
Access and modify node properties including names, distances, and custom attributes.
# Core Properties
name: str # Node name
dist: float # Branch length/distance to parent
support: float # Support value for branch
up: TreeNode # Parent node
children: list # List of child nodes
def add_feature(self, pr_name, pr_value):
"""
Add custom attribute to node.
Parameters:
- pr_name (str): Attribute name
- pr_value: Attribute value
"""
def del_feature(self, pr_name):
"""
Delete custom attribute from node.
Parameters:
- pr_name (str): Attribute name to delete
"""Tree Topology Analysis
Analyze tree structure and relationships between nodes.
def is_leaf(self):
"""
Check if node is a leaf (has no children).
Returns:
bool: True if node is leaf
"""
def is_root(self):
"""
Check if node is root (has no parent).
Returns:
bool: True if node is root
"""
def get_tree_root(self):
"""
Get root node of the tree.
Returns:
TreeNode: Root node
"""
def get_distance(self, target, topology_only=False):
"""
Calculate distance to target node.
Parameters:
- target (TreeNode): Target node
- topology_only (bool): Count only nodes, ignore branch lengths
Returns:
float: Distance to target
"""
def get_closest_leaf(self, topology_only=False):
"""
Find closest leaf node.
Parameters:
- topology_only (bool): Ignore branch lengths
Returns:
tuple: (TreeNode, distance) of closest leaf
"""
def get_farthest_leaf(self, topology_only=False):
"""
Find farthest leaf node.
Parameters:
- topology_only (bool): Ignore branch lengths
Returns:
tuple: (TreeNode, distance) of farthest leaf
"""Tree Modification and Restructuring
Modify tree topology and structure through rooting, pruning, and other operations.
def set_outgroup(self, outgroup):
"""
Root tree using specified outgroup.
Parameters:
- outgroup (TreeNode or list): Outgroup node(s)
Returns:
TreeNode: New root node
"""
def unroot(self):
"""
Remove root by creating multifurcation at root.
"""
def prune(self, nodes, preserve_branch_length=False):
"""
Remove specified nodes from tree.
Parameters:
- nodes (list): Nodes to remove
- preserve_branch_length (bool): Preserve branch lengths
"""
def ladderize(self, direction=0):
"""
Sort tree for ladder-like appearance.
Parameters:
- direction (int): 0 for ascending, 1 for descending
"""
def resolve_polytomy(self, default_dist=0.0, default_support=0.0):
"""
Resolve polytomies by adding internal nodes.
Parameters:
- default_dist (float): Default branch length for new branches
- default_support (float): Default support for new branches
"""
def sort_descendants(self, attr="name"):
"""
Sort descendants by attribute.
Parameters:
- attr (str): Attribute name to sort by
"""
def standardize(self):
"""
Standardize tree structure (ladderize + sort).
"""
def swap_children(self):
"""
Swap positions of child nodes.
"""Tree Copying and Serialization
Create copies of trees and export to various formats.
def copy(self, method="cpickle"):
"""
Create copy of tree.
Parameters:
- method (str): Copy method ("cpickle", "deepcopy")
Returns:
TreeNode: Copied tree
"""
def write(self, features=None, outdir=None, format=0, is_leaf_fn=None):
"""
Export tree to Newick format.
Parameters:
- features (list): Node features to include
- outdir (str): Output directory
- format (int): Newick format (0-9)
- is_leaf_fn (function): Custom leaf detection function
Returns:
str: Newick representation
"""Node Search and Filtering
Search for nodes based on attributes and conditions.
def search_nodes(self, **conditions):
"""
Search for nodes matching conditions.
Parameters:
- conditions: Keyword arguments for attribute matching
Returns:
list: Matching TreeNode objects
"""
def iter_search_nodes(self, **conditions):
"""
Iterator version of search_nodes.
Parameters:
- conditions: Keyword arguments for attribute matching
Yields:
TreeNode: Each matching node
"""
def get_leaf_names(self):
"""
Get names of all leaf nodes.
Returns:
list: List of leaf names
"""Tree Validation and Utility
Utility functions for tree validation and manipulation.
def populate(self, size, names_library=None, reuse_names=True):
"""
Populate tree with random topology.
Parameters:
- size (int): Number of leaf nodes
- names_library (list): Names to use for nodes
- reuse_names (bool): Allow name reuse
Returns:
TreeNode: Populated tree
"""
def get_cached_content(self, store_attr=None):
"""
Get cached tree content for performance.
Parameters:
- store_attr (str): Attribute to cache
Returns:
dict: Cached content
"""Tree Error Handling
class TreeError(Exception):
"""Exception raised for tree operation errors."""
passUsage Examples
Basic Tree Operations
from ete3 import Tree
# Create tree from Newick string
t = Tree("(A:1,(B:1,(E:1,D:1):0.5):0.5);")
# Basic properties
print(f"Tree size: {len(t)}")
print(f"Is leaf: {t.is_leaf()}")
print(f"Children: {len(t.children)}")
# Traverse tree
for node in t.traverse("postorder"):
print(f"Node {node.name}: {node.dist}")
# Find specific nodes
leaves = t.get_leaves()
ancestors = t.get_ancestors()
# Modify tree
child = t.add_child(name="F", dist=0.8)
t.remove_child(child)Tree Manipulation
# Root tree with outgroup
t.set_outgroup(t&"A") # & operator for node access
# Prune nodes
t.prune([t&"B", t&"C"])
# Copy tree
t2 = t.copy()
# Export to Newick
newick_str = t.write(format=1)Install with Tessl CLI
npx tessl i tessl/pypi-ete3