0
# Core Data Models
1
2
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.
3
4
## Capabilities
5
6
### Tree Class
7
8
The primary class for representing phylogenetic trees with comprehensive methods for tree manipulation, traversal, and analysis.
9
10
```python { .api }
11
class Tree:
12
"""
13
Phylogenetic tree class with nodes, edges, and taxon associations.
14
15
Parameters:
16
- taxon_namespace: TaxonNamespace object for taxon management
17
- seed_node: Root node of the tree
18
- is_rooted: Whether tree should be treated as rooted
19
- label: Optional label for the tree
20
"""
21
22
def __init__(self, taxon_namespace=None, seed_node=None, is_rooted=None, label=None): ...
23
24
@classmethod
25
def get(cls, **kwargs):
26
"""
27
Factory method to read tree from file or other source.
28
29
Parameters:
30
- file/path/url/data: Source of tree data
31
- schema: Format specification ('newick', 'nexus', 'nexml', etc.)
32
- preserve_underscores: Keep underscores in taxon names
33
- suppress_internal_node_taxa: Ignore internal node labels as taxa
34
- rooting: How to handle rooting ('force-rooted', 'force-unrooted', 'default-rooted', 'default-unrooted')
35
36
Returns:
37
Tree object
38
"""
39
40
def read(self, **kwargs):
41
"""Read tree data from source into existing tree object."""
42
43
def write(self, **kwargs):
44
"""Write tree to file or stream in specified format."""
45
46
def write_to_stream(self, dest, schema, **kwargs):
47
"""Write tree to stream in specified format."""
48
49
# Tree structure access
50
def nodes(self):
51
"""Returns list of all nodes in tree."""
52
53
def leaf_nodes(self):
54
"""Returns list of all leaf (terminal) nodes."""
55
56
def internal_nodes(self):
57
"""Returns list of all internal nodes."""
58
59
def edges(self):
60
"""Returns list of all edges in tree."""
61
62
def leaf_edges(self):
63
"""Returns list of all edges leading to leaves."""
64
65
def internal_edges(self):
66
"""Returns list of all internal edges."""
67
68
# Tree traversal iterators
69
def preorder_node_iter(self, filter_fn=None):
70
"""Iterate over nodes in preorder."""
71
72
def postorder_node_iter(self, filter_fn=None):
73
"""Iterate over nodes in postorder."""
74
75
def levelorder_node_iter(self, filter_fn=None):
76
"""Iterate over nodes level by level."""
77
78
def leaf_node_iter(self, filter_fn=None):
79
"""Iterate over leaf nodes only."""
80
81
# Node search and access
82
def find_node(self, filter_fn):
83
"""Find first node matching filter function."""
84
85
def find_nodes(self, filter_fn):
86
"""Find all nodes matching filter function."""
87
88
def find_node_with_label(self, label):
89
"""Find node with specific label."""
90
91
def find_node_for_taxon(self, taxon):
92
"""Find node associated with specific taxon."""
93
94
def mrca(self, **kwargs):
95
"""Find most recent common ancestor of specified taxa or nodes."""
96
97
# Tree manipulation
98
def apply(self, before_fn=None, after_fn=None, leaf_fn=None):
99
"""Apply functions to nodes during tree traversal."""
100
101
def update_taxon_namespace(self):
102
"""Update taxon namespace based on current leaf nodes."""
103
104
def poll_taxa(self, taxa=None):
105
"""Populate leaf nodes with taxa from namespace."""
106
107
def randomly_assign_taxa(self, taxon_namespace=None, rng=None):
108
"""Randomly assign taxa to leaf nodes."""
109
110
def resolve_polytomies(self, limit=2, update_bipartitions=True, rng=None):
111
"""Resolve polytomies by adding internal nodes."""
112
113
def collapse_basal_bifurcation(self, set_as_unrooted_tree=True):
114
"""Collapse basal bifurcation in rooted tree."""
115
116
# Tree properties and statistics
117
def max_distance_from_root(self):
118
"""Maximum distance from root to any leaf."""
119
120
def length(self):
121
"""Sum of all edge lengths in tree."""
122
123
def is_ultrametric(self, tol=1e-5):
124
"""Check if tree is ultrametric (all leaves equidistant from root)."""
125
```
126
127
### Node Class
128
129
Represents individual nodes (vertices) in phylogenetic trees with parent-child relationships and optional taxon associations.
130
131
```python { .api }
132
class Node:
133
"""
134
Tree node with parent-child relationships and metadata.
135
136
Parameters:
137
- taxon: Associated Taxon object
138
- label: Node label
139
- edge_length: Length of edge leading to this node
140
"""
141
142
def __init__(self, taxon=None, label=None, edge_length=None): ...
143
144
# Node relationships
145
def add_child(self, node):
146
"""Add child node."""
147
148
def new_child(self, **kwargs):
149
"""Create and add new child node."""
150
151
def insert_child(self, index, node):
152
"""Insert child at specific position."""
153
154
def remove_child(self, node, suppress_unifurcations=True):
155
"""Remove child node."""
156
157
def clear_child_nodes(self):
158
"""Remove all child nodes."""
159
160
# Tree traversal from this node
161
def preorder_iter(self, filter_fn=None):
162
"""Iterate descendants in preorder."""
163
164
def postorder_iter(self, filter_fn=None):
165
"""Iterate descendants in postorder."""
166
167
def levelorder_iter(self, filter_fn=None):
168
"""Iterate descendants level by level."""
169
170
def leaf_iter(self, filter_fn=None):
171
"""Iterate over descendant leaves."""
172
173
def ancestor_iter(self, filter_fn=None, inclusive=True):
174
"""Iterate over ancestors toward root."""
175
176
def sibling_iter(self, filter_fn=None):
177
"""Iterate over sibling nodes."""
178
179
# Node access and queries
180
def leaf_nodes(self):
181
"""Get all descendant leaf nodes."""
182
183
def internal_nodes(self):
184
"""Get all descendant internal nodes."""
185
186
def is_leaf(self):
187
"""Check if node is a leaf."""
188
189
def is_internal(self):
190
"""Check if node is internal."""
191
192
def num_child_nodes(self):
193
"""Number of immediate children."""
194
195
def distance_from_root(self):
196
"""Distance from root node."""
197
198
def distance_from_tip(self):
199
"""Distance to furthest descendant leaf."""
200
201
# Node manipulation
202
def collapse_clade(self, map_attributes=None):
203
"""Collapse this node's entire clade."""
204
205
def collapse_neighborhood(self, distance):
206
"""Collapse nodes within specified distance."""
207
208
def extract_subtree(self, **kwargs):
209
"""Extract subtree rooted at this node."""
210
```
211
212
### Taxon and TaxonNamespace
213
214
Classes for managing operational taxonomic units and their namespaces across phylogenetic data structures.
215
216
```python { .api }
217
class Taxon:
218
"""
219
Operational taxonomic unit representation.
220
221
Parameters:
222
- label: Taxon name/identifier
223
"""
224
225
def __init__(self, label=None): ...
226
227
# Taxon properties
228
@property
229
def label(self):
230
"""Taxon label/name."""
231
232
@label.setter
233
def label(self, value): ...
234
235
class TaxonNamespace:
236
"""
237
Collection and manager of Taxon objects.
238
239
Parameters:
240
- taxa: Initial list of taxa or taxon labels
241
- label: Label for this namespace
242
- is_mutable: Whether taxa can be added/removed
243
"""
244
245
def __init__(self, taxa=None, label=None, is_mutable=True): ...
246
247
# Taxon management
248
def new_taxon(self, label):
249
"""Create and add new taxon with given label."""
250
251
def require_taxon(self, label):
252
"""Get existing taxon or create new one with label."""
253
254
def get_taxon(self, label):
255
"""Get taxon by label, return None if not found."""
256
257
def add_taxon(self, taxon):
258
"""Add existing Taxon object."""
259
260
def remove_taxon(self, taxon):
261
"""Remove taxon from namespace."""
262
263
def clear(self):
264
"""Remove all taxa."""
265
266
# Namespace access
267
def __len__(self):
268
"""Number of taxa in namespace."""
269
270
def __iter__(self):
271
"""Iterate over taxa."""
272
273
def __getitem__(self, index):
274
"""Get taxon by index or label."""
275
276
def __contains__(self, taxon_or_label):
277
"""Check if taxon exists in namespace."""
278
279
def labels(self):
280
"""List of all taxon labels."""
281
282
def complement(self, taxa):
283
"""Return taxa not in given collection."""
284
285
# Legacy alias
286
TaxonSet = TaxonNamespace
287
```
288
289
### Tree Collections
290
291
Classes for managing collections of phylogenetic trees with shared taxon namespaces.
292
293
```python { .api }
294
class TreeList:
295
"""
296
List-like collection of Tree objects with shared taxon namespace.
297
298
Parameters:
299
- trees: Initial list of trees
300
- taxon_namespace: Shared taxon namespace
301
"""
302
303
def __init__(self, trees=None, taxon_namespace=None): ...
304
305
@classmethod
306
def get(cls, **kwargs):
307
"""Read multiple trees from source."""
308
309
def read(self, **kwargs):
310
"""Read trees from source into existing collection."""
311
312
def write(self, **kwargs):
313
"""Write all trees to file or stream."""
314
315
# List-like interface
316
def __len__(self): ...
317
def __iter__(self): ...
318
def __getitem__(self, index): ...
319
def __setitem__(self, index, tree): ...
320
def append(self, tree): ...
321
def extend(self, trees): ...
322
def remove(self, tree): ...
323
def clear(self): ...
324
325
class TreeArray:
326
"""Array-like collection of trees optimized for large tree sets."""
327
328
def __init__(self, **kwargs): ...
329
330
class SplitDistribution:
331
"""
332
Distribution of bipartitions (splits) across a set of trees.
333
334
Parameters:
335
- taxon_namespace: Taxon namespace for split calculations
336
"""
337
338
def __init__(self, taxon_namespace=None): ...
339
340
def count_splits_on_tree(self, tree, split_weights=None):
341
"""Count splits from tree and add to distribution."""
342
343
def count_splits_on_trees(self, trees, split_weights=None):
344
"""Count splits from multiple trees."""
345
346
def frequency_of_split(self, split):
347
"""Get frequency of specific split."""
348
349
def splits(self):
350
"""Iterator over all splits."""
351
```
352
353
### Dataset Container
354
355
Container class for managing multiple data types (trees and character matrices) with shared taxon namespaces.
356
357
```python { .api }
358
class DataSet:
359
"""
360
Container for multiple trees and character matrices with shared taxa.
361
362
Parameters:
363
- taxon_namespaces: List of TaxonNamespace objects
364
"""
365
366
def __init__(self, taxon_namespaces=None): ...
367
368
@classmethod
369
def get(cls, **kwargs):
370
"""Read dataset from file containing mixed data types."""
371
372
def read(self, **kwargs):
373
"""Read data from source into existing dataset."""
374
375
def write(self, **kwargs):
376
"""Write entire dataset to file."""
377
378
# Data access
379
@property
380
def tree_lists(self):
381
"""List of TreeList objects in dataset."""
382
383
@property
384
def char_matrices(self):
385
"""List of CharacterMatrix objects in dataset."""
386
387
@property
388
def taxon_namespaces(self):
389
"""List of TaxonNamespace objects."""
390
391
def new_tree_list(self, **kwargs):
392
"""Create new TreeList in this dataset."""
393
394
def new_char_matrix(self, char_matrix_type, **kwargs):
395
"""Create new CharacterMatrix in this dataset."""
396
397
def migrate_taxon_namespace(self, taxon_namespace, **kwargs):
398
"""Migrate data objects to different taxon namespace."""
399
```
400
401
## Base Classes and Interfaces
402
403
```python { .api }
404
class DataObject:
405
"""Base class for all phylogenetic data objects."""
406
407
class Annotable:
408
"""Interface for objects that can have annotations."""
409
410
def annotate(self, name, value, datatype_hint=None, name_prefix=None): ...
411
def clear_annotations(self): ...
412
413
class Annotation:
414
"""Key-value annotation with optional datatype."""
415
416
def __init__(self, name, value, datatype_hint=None, name_prefix=None): ...
417
418
class AnnotationSet:
419
"""Collection of Annotation objects."""
420
421
def __init__(self): ...
422
def add(self, annotation): ...
423
def findall(self, name=None, **kwargs): ...
424
```