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
simulation.mddocs/
Simulation & Modeling
Tree simulation using birth-death and coalescent processes, character evolution simulation, and phylogenetic modeling. DendroPy provides comprehensive tools for simulating phylogenetic trees and evolving character data under various evolutionary models.
Capabilities
Tree Simulation
Functions for simulating phylogenetic trees under different evolutionary processes.
def birth_death_tree(birth_rate, death_rate, **kwargs):
"""
Simulate tree under birth-death process.
Parameters:
- birth_rate: Per-lineage birth (speciation) rate
- death_rate: Per-lineage death (extinction) rate
- taxon_namespace: TaxonNamespace for tip taxa
- num_extant_tips: Number of extant taxa to simulate
- num_total_tips: Total number of taxa (including extinct)
- max_time: Maximum time for simulation
- gsa_ntax: General sampling approach target taxa
- is_retain_extinct_tips: Keep extinct lineages in tree
- repeat_until_success: Retry if simulation goes extinct
- rng: Random number generator
Returns:
Tree: Simulated birth-death tree
"""
def discrete_birth_death_tree(birth_rate, death_rate, **kwargs):
"""
Simulate tree under discrete birth-death process.
Parameters:
- birth_rate: Birth rate per time step
- death_rate: Death rate per time step
- max_time: Maximum simulation time
- num_time_steps: Number of discrete time steps
- **kwargs: Additional birth-death parameters
Returns:
Tree: Simulated discrete birth-death tree
"""
def uniform_pure_birth_tree(taxon_namespace, birth_rate=1.0, **kwargs):
"""
Simulate tree under pure birth (Yule) process.
Parameters:
- taxon_namespace: TaxonNamespace defining tip taxa
- birth_rate: Speciation rate (default: 1.0)
- is_assign_extant_taxa: Assign taxa to extant tips
- rng: Random number generator
Returns:
Tree: Simulated pure birth tree
"""
def star_tree(taxon_namespace, **kwargs):
"""
Create star tree (polytomy) with all taxa sister to each other.
Parameters:
- taxon_namespace: TaxonNamespace for tip taxa
- edge_length: Length for all terminal edges
Returns:
Tree: Star-shaped tree
"""
def rand_trees(taxon_namespace, num_trees, **kwargs):
"""
Generate collection of random trees.
Parameters:
- taxon_namespace: TaxonNamespace for trees
- num_trees: Number of trees to generate
- tree_factory: Function for generating individual trees
- rng: Random number generator
Returns:
TreeList: Collection of random trees
"""Coalescent Simulation
Functions for simulating trees under coalescent processes.
def contained_coalescent_tree(containing_tree, gene_to_species_map, **kwargs):
"""
Simulate gene tree contained within species tree using coalescent.
Parameters:
- containing_tree: Species tree containing gene tree
- gene_to_species_map: Mapping from gene taxa to species taxa
- default_pop_size: Default population size for branches
- rng: Random number generator
Returns:
Tree: Simulated gene tree embedded in species tree
"""
def pure_kingman_tree(taxon_namespace, pop_size=1, **kwargs):
"""
Simulate tree under pure Kingman coalescent.
Parameters:
- taxon_namespace: TaxonNamespace for coalescent taxa
- pop_size: Effective population size
- rng: Random number generator
Returns:
Tree: Simulated coalescent tree
"""
def mean_kingman_tree(taxon_namespace, pop_size=1, **kwargs):
"""
Generate tree with expected coalescent times.
Parameters:
- taxon_namespace: TaxonNamespace for taxa
- pop_size: Effective population size
Returns:
Tree: Tree with mean coalescent branch lengths
"""
def constrained_kingman_tree(pop_tree, gene_tree_list=None, **kwargs):
"""
Simulate constrained coalescent tree within population tree.
Parameters:
- pop_tree: Population/species tree providing constraints
- gene_tree_list: List to store simulated gene trees
- num_genes: Number of gene trees to simulate
- pop_sizes: Population sizes for each branch
- rng: Random number generator
Returns:
Tree or TreeList: Simulated constrained coalescent tree(s)
"""Population Genetics Simulation
Functions for simulating population genetic processes and genealogies.
def pop_gen_tree(num_genes, pop_size=1, **kwargs):
"""
Simulate population genetics tree (gene genealogy).
Parameters:
- num_genes: Number of gene copies to simulate
- pop_size: Effective population size
- num_gens: Number of generations to simulate
- rng: Random number generator
Returns:
Tree: Simulated gene genealogy
"""
def fragmented_tree(taxon_namespace, fragment_probs, **kwargs):
"""
Simulate tree with fragmented (missing) taxa.
Parameters:
- taxon_namespace: Complete set of taxa
- fragment_probs: Probability of each taxon being present
- base_tree: Base tree structure for fragmentation
- rng: Random number generator
Returns:
Tree: Tree with some taxa removed
"""Character Evolution Simulation
Comprehensive character evolution simulation under various models.
def simulate_discrete_char_dataset(tree, seq_len, **kwargs):
"""
Simulate discrete character dataset on phylogenetic tree.
Parameters:
- tree: Tree for character evolution
- seq_len: Length of character sequences
- char_model: Character evolution model (JC69, HKY85, etc.)
- mutation_rate: Overall mutation rate multiplier
- site_rates: Rate variation across sites
- invariant_sites_prop: Proportion of invariant sites
- rng: Random number generator
Returns:
CharacterMatrix: Simulated character alignment
"""
def simulate_discrete_chars(tree, char_model, seq_len, **kwargs):
"""
Simulate discrete characters with specified evolutionary model.
Parameters:
- tree: Phylogenetic tree with branch lengths
- char_model: DiscreteCharacterEvolutionModel instance
- seq_len: Number of characters to simulate
- root_states: Ancestral character states
- rng: Random number generator
Returns:
CharacterMatrix: Evolved discrete character data
"""
def hky85_chars(tree, seq_len, **kwargs):
"""
Simulate DNA evolution under HKY85 substitution model.
Parameters:
- tree: Phylogenetic tree with branch lengths in substitutions
- seq_len: DNA sequence length
- kappa: Transition/transversion ratio (default: 1.0)
- base_freqs: Equilibrium base frequencies [fA, fC, fG, fT]
- mutation_rate: Rate multiplier for all substitutions
- site_rates: Gamma-distributed rate variation
- invariant_sites_prop: Proportion of invariant sites
- rng: Random number generator
Returns:
DnaCharacterMatrix: Simulated DNA sequences
"""
def jc69_chars(tree, seq_len, **kwargs):
"""
Simulate DNA evolution under Jukes-Cantor 69 model.
Parameters:
- tree: Phylogenetic tree with branch lengths
- seq_len: DNA sequence length
- mutation_rate: Substitution rate
- rng: Random number generator
Returns:
DnaCharacterMatrix: Simulated DNA sequences
"""
def evolve_continuous_char(tree, char_matrix, **kwargs):
"""
Evolve continuous characters using Brownian motion.
Parameters:
- tree: Phylogenetic tree
- char_matrix: Starting continuous character values
- rate: Rate of continuous character evolution
- model: Evolution model ('brownian', 'ou', etc.)
- rng: Random number generator
Returns:
ContinuousCharacterMatrix: Evolved continuous characters
"""Advanced Character Evolution Models
Sophisticated models for character evolution including rate variation and complex substitution patterns.
class DiscreteCharacterEvolutionModel:
"""
Base class for discrete character evolution models.
Parameters:
- state_alphabet: StateAlphabet defining character states
- stationary_freqs: Equilibrium state frequencies
- rate_matrix: Instantaneous rate matrix Q
"""
def __init__(self, state_alphabet=None, **kwargs): ...
def p_matrix(self, edge_length):
"""Calculate transition probability matrix P(t) = exp(Qt)."""
def simulate_ancestral_states(self, num_chars, rng=None):
"""Simulate ancestral character states."""
def evolve_states(self, tree, seq_len, **kwargs):
"""Evolve character states on tree."""
class Hky85(DiscreteCharacterEvolutionModel):
"""
HKY85 nucleotide substitution model.
Parameters:
- kappa: Transition/transversion rate ratio
- base_freqs: Equilibrium base frequencies [fA, fC, fG, fT]
"""
def __init__(self, kappa=1.0, base_freqs=None): ...
class Jc69(DiscreteCharacterEvolutionModel):
"""
Jukes-Cantor 69 nucleotide substitution model.
Equal substitution rates and base frequencies.
"""
def __init__(self): ...
class Gtr(DiscreteCharacterEvolutionModel):
"""
General Time Reversible nucleotide substitution model.
Parameters:
- rate_params: Six substitution rate parameters
- base_freqs: Equilibrium base frequencies
"""
def __init__(self, rate_params=None, base_freqs=None): ...
class DiscreteCharacterEvolver:
"""
Engine for evolving discrete characters along phylogenetic trees.
Parameters:
- seq_model: DiscreteCharacterEvolutionModel
- mutation_rate: Overall rate multiplier
- site_rates: Rate heterogeneity across sites
"""
def __init__(self, seq_model=None, **kwargs): ...
def evolve_states(self, tree, seq_len, **kwargs):
"""
Simulate character evolution on tree.
Parameters:
- tree: Tree for simulation
- seq_len: Number of characters
- root_states: Starting character states
- rng: Random number generator
Returns:
CharacterMatrix: Simulated character data
"""Rate Variation Models
Models for rate variation across sites and lineages.
def gamma_site_rates(alpha, num_categories=4, **kwargs):
"""
Generate gamma-distributed rate categories for sites.
Parameters:
- alpha: Shape parameter for gamma distribution
- num_categories: Number of discrete rate categories
- rng: Random number generator
Returns:
list: Rate multipliers for each category
"""
def invariant_sites_model(prop_invariant, site_rates=None):
"""
Create model with proportion of invariant sites.
Parameters:
- prop_invariant: Proportion of sites that never change
- site_rates: Rate categories for variable sites
Returns:
list: Rate categories including invariant sites (rate=0)
"""
def codon_position_rates(rates_123):
"""
Set different rates for codon positions.
Parameters:
- rates_123: Rates for 1st, 2nd, 3rd codon positions
Returns:
list: Site-specific rate multipliers
"""Tree Modification for Simulation
Functions for modifying trees to prepare them for simulation.
def scale_tree(tree, scaling_factor):
"""
Scale all branch lengths in tree.
Parameters:
- tree: Tree to scale
- scaling_factor: Multiplier for all branch lengths
Returns:
None (modifies tree in place)
"""
def set_uniform_branch_lengths(tree, length=1.0):
"""
Set all branches to same length.
Parameters:
- tree: Tree to modify
- length: Branch length to assign
Returns:
None (modifies tree in place)
"""
def add_rate_variation_to_tree(tree, rate_distribution, **kwargs):
"""
Add rate variation across tree branches.
Parameters:
- tree: Tree to modify
- rate_distribution: Distribution for sampling rates
- rng: Random number generator
Returns:
None (modifies branch lengths in place)
"""
def ultrametrize_tree(tree, **kwargs):
"""
Convert tree to ultrametric (molecular clock).
Parameters:
- tree: Tree to ultrametrize
- strategy: Method ('equal', 'proportional', 'minimize_change')
Returns:
None (modifies tree in place)
"""Simulation Utilities
Utility functions for managing and analyzing simulated data.
def repeat_simulation(simulation_fn, num_replicates, **kwargs):
"""
Repeat simulation multiple times.
Parameters:
- simulation_fn: Function that performs one simulation
- num_replicates: Number of simulation replicates
- **kwargs: Arguments passed to simulation function
Returns:
list: Results from all simulation replicates
"""
def simulation_summary_stats(simulated_trees, **kwargs):
"""
Calculate summary statistics on simulated trees.
Parameters:
- simulated_trees: Collection of simulated Tree objects
- stats: List of statistics to calculate
Returns:
dict: Summary statistics across simulations
"""
def validate_simulation_parameters(tree, char_model, **kwargs):
"""
Validate parameters for character evolution simulation.
Parameters:
- tree: Tree for simulation
- char_model: Character evolution model
- **kwargs: Additional simulation parameters
Returns:
bool: True if parameters are valid
Raises:
ValueError: If parameters are invalid
"""Install with Tessl CLI
npx tessl i tessl/pypi-dendropy