tessl/pypi-dendropy

A Python library for phylogenetics and phylogenetic computing: reading, writing, simulation, processing and manipulation of phylogenetic trees and characters.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Core Data Models

Name: tessl/pypi-dendropy
Author: tessl

Fundamental phylogenetic data structures that form the foundation of DendroPy's phylogenetic computing capabilities. These classes represent trees, nodes, taxa, character matrices, and datasets with rich metadata support and automatic taxon namespace management.

Capabilities

Tree Class

The primary class for representing phylogenetic trees with comprehensive methods for tree manipulation, traversal, and analysis.

class Tree:
    """
    Phylogenetic tree class with nodes, edges, and taxon associations.
    
    Parameters:
    - taxon_namespace: TaxonNamespace object for taxon management
    - seed_node: Root node of the tree
    - is_rooted: Whether tree should be treated as rooted
    - label: Optional label for the tree
    """
    
    def __init__(self, taxon_namespace=None, seed_node=None, is_rooted=None, label=None): ...
    
    @classmethod
    def get(cls, **kwargs):
        """
        Factory method to read tree from file or other source.
        
        Parameters:
        - file/path/url/data: Source of tree data
        - schema: Format specification ('newick', 'nexus', 'nexml', etc.)
        - preserve_underscores: Keep underscores in taxon names
        - suppress_internal_node_taxa: Ignore internal node labels as taxa
        - rooting: How to handle rooting ('force-rooted', 'force-unrooted', 'default-rooted', 'default-unrooted')
        
        Returns:
        Tree object
        """
    
    def read(self, **kwargs):
        """Read tree data from source into existing tree object."""
    
    def write(self, **kwargs):
        """Write tree to file or stream in specified format."""
    
    def write_to_stream(self, dest, schema, **kwargs):
        """Write tree to stream in specified format."""
    
    # Tree structure access
    def nodes(self):
        """Returns list of all nodes in tree."""
    
    def leaf_nodes(self):
        """Returns list of all leaf (terminal) nodes."""
    
    def internal_nodes(self):
        """Returns list of all internal nodes."""
    
    def edges(self):
        """Returns list of all edges in tree."""
    
    def leaf_edges(self):
        """Returns list of all edges leading to leaves."""
    
    def internal_edges(self):
        """Returns list of all internal edges."""
    
    # Tree traversal iterators
    def preorder_node_iter(self, filter_fn=None):
        """Iterate over nodes in preorder."""
    
    def postorder_node_iter(self, filter_fn=None):
        """Iterate over nodes in postorder."""
    
    def levelorder_node_iter(self, filter_fn=None):
        """Iterate over nodes level by level."""
    
    def leaf_node_iter(self, filter_fn=None):
        """Iterate over leaf nodes only."""
    
    # Node search and access
    def find_node(self, filter_fn):
        """Find first node matching filter function."""
    
    def find_nodes(self, filter_fn):
        """Find all nodes matching filter function."""
    
    def find_node_with_label(self, label):
        """Find node with specific label."""
    
    def find_node_for_taxon(self, taxon):
        """Find node associated with specific taxon."""
    
    def mrca(self, **kwargs):
        """Find most recent common ancestor of specified taxa or nodes."""
    
    # Tree manipulation
    def apply(self, before_fn=None, after_fn=None, leaf_fn=None):
        """Apply functions to nodes during tree traversal."""
    
    def update_taxon_namespace(self):
        """Update taxon namespace based on current leaf nodes."""
    
    def poll_taxa(self, taxa=None):
        """Populate leaf nodes with taxa from namespace."""
    
    def randomly_assign_taxa(self, taxon_namespace=None, rng=None):
        """Randomly assign taxa to leaf nodes."""
    
    def resolve_polytomies(self, limit=2, update_bipartitions=True, rng=None):
        """Resolve polytomies by adding internal nodes."""
    
    def collapse_basal_bifurcation(self, set_as_unrooted_tree=True):
        """Collapse basal bifurcation in rooted tree."""
    
    # Tree properties and statistics
    def max_distance_from_root(self):
        """Maximum distance from root to any leaf."""
    
    def length(self):
        """Sum of all edge lengths in tree."""
    
    def is_ultrametric(self, tol=1e-5):
        """Check if tree is ultrametric (all leaves equidistant from root)."""

Node Class

Represents individual nodes (vertices) in phylogenetic trees with parent-child relationships and optional taxon associations.

class Node:
    """
    Tree node with parent-child relationships and metadata.
    
    Parameters:
    - taxon: Associated Taxon object
    - label: Node label
    - edge_length: Length of edge leading to this node
    """
    
    def __init__(self, taxon=None, label=None, edge_length=None): ...
    
    # Node relationships
    def add_child(self, node):
        """Add child node."""
    
    def new_child(self, **kwargs):
        """Create and add new child node."""
    
    def insert_child(self, index, node):
        """Insert child at specific position."""
    
    def remove_child(self, node, suppress_unifurcations=True):
        """Remove child node."""
    
    def clear_child_nodes(self):
        """Remove all child nodes."""
    
    # Tree traversal from this node
    def preorder_iter(self, filter_fn=None):
        """Iterate descendants in preorder."""
    
    def postorder_iter(self, filter_fn=None):
        """Iterate descendants in postorder."""
    
    def levelorder_iter(self, filter_fn=None):
        """Iterate descendants level by level."""
    
    def leaf_iter(self, filter_fn=None):
        """Iterate over descendant leaves."""
    
    def ancestor_iter(self, filter_fn=None, inclusive=True):
        """Iterate over ancestors toward root."""
    
    def sibling_iter(self, filter_fn=None):
        """Iterate over sibling nodes."""
    
    # Node access and queries
    def leaf_nodes(self):
        """Get all descendant leaf nodes."""
    
    def internal_nodes(self):
        """Get all descendant internal nodes."""
    
    def is_leaf(self):
        """Check if node is a leaf."""
    
    def is_internal(self):
        """Check if node is internal."""
    
    def num_child_nodes(self):
        """Number of immediate children."""
    
    def distance_from_root(self):
        """Distance from root node."""
    
    def distance_from_tip(self):
        """Distance to furthest descendant leaf."""
    
    # Node manipulation
    def collapse_clade(self, map_attributes=None):
        """Collapse this node's entire clade."""
    
    def collapse_neighborhood(self, distance):
        """Collapse nodes within specified distance."""
    
    def extract_subtree(self, **kwargs):
        """Extract subtree rooted at this node."""

Taxon and TaxonNamespace

Classes for managing operational taxonomic units and their namespaces across phylogenetic data structures.

class Taxon:
    """
    Operational taxonomic unit representation.
    
    Parameters:
    - label: Taxon name/identifier
    """
    
    def __init__(self, label=None): ...
    
    # Taxon properties
    @property
    def label(self):
        """Taxon label/name."""
    
    @label.setter
    def label(self, value): ...

class TaxonNamespace:
    """
    Collection and manager of Taxon objects.
    
    Parameters:
    - taxa: Initial list of taxa or taxon labels
    - label: Label for this namespace
    - is_mutable: Whether taxa can be added/removed
    """
    
    def __init__(self, taxa=None, label=None, is_mutable=True): ...
    
    # Taxon management
    def new_taxon(self, label):
        """Create and add new taxon with given label."""
    
    def require_taxon(self, label):
        """Get existing taxon or create new one with label."""
    
    def get_taxon(self, label):
        """Get taxon by label, return None if not found."""
    
    def add_taxon(self, taxon):
        """Add existing Taxon object."""
    
    def remove_taxon(self, taxon):
        """Remove taxon from namespace."""
    
    def clear(self):
        """Remove all taxa."""
    
    # Namespace access
    def __len__(self):
        """Number of taxa in namespace."""
    
    def __iter__(self):
        """Iterate over taxa."""
    
    def __getitem__(self, index):
        """Get taxon by index or label."""
    
    def __contains__(self, taxon_or_label):
        """Check if taxon exists in namespace."""
    
    def labels(self):
        """List of all taxon labels."""
    
    def complement(self, taxa):
        """Return taxa not in given collection."""

# Legacy alias
TaxonSet = TaxonNamespace

Tree Collections

Classes for managing collections of phylogenetic trees with shared taxon namespaces.

class TreeList:
    """
    List-like collection of Tree objects with shared taxon namespace.
    
    Parameters:
    - trees: Initial list of trees
    - taxon_namespace: Shared taxon namespace
    """
    
    def __init__(self, trees=None, taxon_namespace=None): ...
    
    @classmethod
    def get(cls, **kwargs):
        """Read multiple trees from source."""
    
    def read(self, **kwargs):
        """Read trees from source into existing collection."""
    
    def write(self, **kwargs):
        """Write all trees to file or stream."""
    
    # List-like interface
    def __len__(self): ...
    def __iter__(self): ...
    def __getitem__(self, index): ...
    def __setitem__(self, index, tree): ...
    def append(self, tree): ...
    def extend(self, trees): ...
    def remove(self, tree): ...
    def clear(self): ...

class TreeArray:
    """Array-like collection of trees optimized for large tree sets."""
    
    def __init__(self, **kwargs): ...

class SplitDistribution:
    """
    Distribution of bipartitions (splits) across a set of trees.
    
    Parameters:
    - taxon_namespace: Taxon namespace for split calculations
    """
    
    def __init__(self, taxon_namespace=None): ...
    
    def count_splits_on_tree(self, tree, split_weights=None):
        """Count splits from tree and add to distribution."""
    
    def count_splits_on_trees(self, trees, split_weights=None):
        """Count splits from multiple trees."""
    
    def frequency_of_split(self, split):
        """Get frequency of specific split."""
    
    def splits(self):
        """Iterator over all splits."""

Dataset Container

Container class for managing multiple data types (trees and character matrices) with shared taxon namespaces.

class DataSet:
    """
    Container for multiple trees and character matrices with shared taxa.
    
    Parameters:
    - taxon_namespaces: List of TaxonNamespace objects
    """
    
    def __init__(self, taxon_namespaces=None): ...
    
    @classmethod
    def get(cls, **kwargs):
        """Read dataset from file containing mixed data types."""
    
    def read(self, **kwargs):
        """Read data from source into existing dataset."""
    
    def write(self, **kwargs):
        """Write entire dataset to file."""
    
    # Data access
    @property
    def tree_lists(self):
        """List of TreeList objects in dataset."""
    
    @property
    def char_matrices(self):
        """List of CharacterMatrix objects in dataset."""
    
    @property
    def taxon_namespaces(self):
        """List of TaxonNamespace objects."""
    
    def new_tree_list(self, **kwargs):
        """Create new TreeList in this dataset."""
    
    def new_char_matrix(self, char_matrix_type, **kwargs):
        """Create new CharacterMatrix in this dataset."""
    
    def migrate_taxon_namespace(self, taxon_namespace, **kwargs):
        """Migrate data objects to different taxon namespace."""

Base Classes and Interfaces

class DataObject:
    """Base class for all phylogenetic data objects."""
    
class Annotable:
    """Interface for objects that can have annotations."""
    
    def annotate(self, name, value, datatype_hint=None, name_prefix=None): ...
    def clear_annotations(self): ...

class Annotation:
    """Key-value annotation with optional datatype."""
    
    def __init__(self, name, value, datatype_hint=None, name_prefix=None): ...

class AnnotationSet:
    """Collection of Annotation objects."""
    
    def __init__(self): ...
    def add(self, annotation): ...
    def findall(self, name=None, **kwargs): ...

Install with Tessl CLI