0
# Tree I/O and Parsing
1

2
TreeSwift provides comprehensive support for reading and writing trees in multiple formats including Newick, Nexus, NeXML, and integration with DendroPy objects. All functions support both string input and file paths (plain-text or gzipped).
3

4
## Capabilities
5

6
### Universal Tree Reader
7

8
The main entry point for reading trees from various formats with automatic format detection and appropriate return types.
9

10
```python { .api }
11
def read_tree(input: str, schema: str) -> Tree | list[Tree] | dict[str, Tree]:
12
    """
13
    Read a tree from a string or file.
14

15
    Parameters:
16
    - input (str): Tree string, path to tree file (plain-text or gzipped), or DendroPy Tree object
17
    - schema (str): Format schema - 'dendropy', 'newick', 'nexml', 'nexus', or 'linkage'
18

19
    Returns:
20
    - Newick: Tree object (single tree) or list[Tree] (multiple trees)
21
    - NeXML/Nexus: dict[str, Tree] with tree names as keys
22
    - DendroPy: Tree object
23
    - Linkage: Tree object or list[Tree] (if return_list=True)
24
    """
25
```
26

27
Usage examples:
28

29
```python
30
import treeswift
31

32
# Read from Newick string
33
tree = treeswift.read_tree("(A,B,C);", "newick")
34

35
# Read from file
36
trees = treeswift.read_tree("mytrees.nexus", "nexus")
37

38
# Read multiple trees from Newick file
39
tree_list = treeswift.read_tree("multiple_trees.nwk", "newick")
40
```
41

42
### Newick Format Reader
43

44
Reads trees from Newick format strings or files, supporting both single and multiple tree inputs.
45

46
```python { .api }
47
def read_tree_newick(newick: str) -> Tree | list[Tree]:
48
    """
49
    Read tree(s) from Newick string or file.
50

51
    Parameters:
52
    - newick (str): Newick string or path to Newick file (plain-text or gzipped)
53

54
    Returns:
55
    - Tree: Single tree object if input contains one tree
56
    - list[Tree]: List of tree objects if input contains multiple trees (one per line)
57
    """
58
```
59

60
Usage examples:
61

62
```python
63
import treeswift
64

65
# Read from Newick string
66
tree = treeswift.read_tree_newick("((A:0.1,B:0.2):0.05,C:0.3):0.0;")
67

68
# Read from Newick file
69
tree = treeswift.read_tree_newick("tree.nwk")
70

71
# Read multiple trees from file
72
trees = treeswift.read_tree_newick("multiple_trees.nwk")
73
for i, tree in enumerate(trees):
74
    print(f"Tree {i+1}: {tree.num_nodes()} nodes")
75

76
# Read from gzipped file
77
tree = treeswift.read_tree_newick("tree.nwk.gz")
78
```
79

80
### Nexus Format Reader
81

82
Reads trees from Nexus format with support for taxon label translation and metadata extraction.
83

84
```python { .api }
85
def read_tree_nexus(nexus: str, translate: bool = True) -> dict[str, Tree]:
86
    """
87
    Read tree(s) from Nexus string or file.
88

89
    Parameters:
90
    - nexus (str): Nexus string or path to Nexus file (plain-text or gzipped)
91
    - translate (bool): Whether to translate node labels using Translate section
92

93
    Returns:
94
    - dict[str, Tree]: Dictionary with tree names as keys and Tree objects as values
95
    - Additional keys may include:
96
      - "taxlabels": list of taxon labels if Taxlabels section exists
97
      - "info": dict of tree metadata if trees have information annotations
98
    """
99
```
100

101
Usage examples:
102

103
```python
104
import treeswift
105

106
# Read from Nexus string
107
nexus_content = """
108
#NEXUS
109
BEGIN TREES;
110
    TREE tree1 = (A,B,C);
111
    TREE tree2 = ((A,B),C);
112
END;
113
"""
114
result = treeswift.read_tree_nexus(nexus_content)
115
tree1 = result["tree1"]
116
tree2 = result["tree2"]
117

118
# Read from Nexus file with translation
119
result = treeswift.read_tree_nexus("trees.nexus", translate=True)
120
for tree_name, tree in result.items():
121
    if isinstance(tree, treeswift.Tree):
122
        print(f"{tree_name}: {tree.num_nodes()} nodes")
123

124
# Access additional metadata
125
if "taxlabels" in result:
126
    print(f"Taxon labels: {result['taxlabels']}")
127
```
128

129
### NeXML Format Reader
130

131
Reads trees from NeXML (XML-based phylogenetic data format) strings or files.
132

133
```python { .api }
134
def read_tree_nexml(nexml: str) -> dict[str, Tree]:
135
    """
136
    Read tree(s) from NeXML string or file.
137

138
    Parameters:
139
    - nexml (str): NeXML string or path to NeXML file (plain-text or gzipped)
140

141
    Returns:
142
    - dict[str, Tree]: Dictionary with tree names as keys and Tree objects as values
143
    """
144
```
145

146
Usage examples:
147

148
```python
149
import treeswift
150

151
# Read from NeXML file
152
trees = treeswift.read_tree_nexml("phylogeny.xml")
153
for tree_name, tree in trees.items():
154
    print(f"{tree_name}: {tree.num_nodes()} nodes, height: {tree.height()}")
155

156
# Read from NeXML string
157
nexml_data = "<nex:nexml>...</nex:nexml>"  # NeXML content
158
trees = treeswift.read_tree_nexml(nexml_data)
159
```
160

161
### DendroPy Integration
162

163
Creates TreeSwift trees from DendroPy Tree objects, enabling interoperability between the two libraries.
164

165
```python { .api }
166
def read_tree_dendropy(tree) -> Tree:
167
    """
168
    Create TreeSwift tree from DendroPy tree.
169

170
    Parameters:
171
    - tree: DendroPy Tree object (dendropy.datamodel.treemodel)
172

173
    Returns:
174
    - Tree: TreeSwift Tree object converted from DendroPy tree
175
    """
176
```
177

178
Usage examples:
179

180
```python
181
import treeswift
182
import dendropy
183

184
# Create DendroPy tree
185
dendro_tree = dendropy.Tree.get(data="(A,B,C);", schema="newick")
186

187
# Convert to TreeSwift
188
ts_tree = treeswift.read_tree_dendropy(dendro_tree)
189
print(f"Converted tree: {ts_tree.num_nodes()} nodes")
190

191
# Preserve rooting information
192
if dendro_tree.is_rooted:
193
    print("Tree is rooted")
194
else:
195
    print("Tree is unrooted")
196
    print(f"TreeSwift is_rooted: {ts_tree.is_rooted}")
197
```
198

199
### Linkage Matrix Reader
200

201
Reads trees from SciPy hierarchical clustering linkage matrices for integration with clustering algorithms.
202

203
```python { .api }
204
def read_tree_linkage(linkage, return_list: bool = False) -> Tree | list[Tree]:
205
    """
206
    Read tree from SciPy linkage matrix.
207

208
    Parameters:
209
    - linkage: NumPy array representing linkage matrix (scipy format)
210
    - return_list (bool): Whether to return list format
211

212
    Returns:
213
    - Tree: Tree object from linkage matrix
214
    - list[Tree]: List of trees if return_list=True
215
    """
216
```
217

218
Usage examples:
219

220
```python
221
import treeswift
222
import numpy as np
223
from scipy.cluster.hierarchy import linkage
224

225
# Create sample data and linkage matrix
226
data = np.array([[0, 0], [1, 1], [2, 0], [3, 1]])
227
linkage_matrix = linkage(data, method='ward')
228

229
# Convert linkage to TreeSwift tree
230
tree = treeswift.read_tree_linkage(linkage_matrix)
231
print(f"Tree from linkage: {tree.newick()}")
232

233
# Get as list format
234
tree_list = treeswift.read_tree_linkage(linkage_matrix, return_list=True)
235
print(f"Trees in list: {len(tree_list)}")
236
```
237

238
### Tree Writing
239

240
Write TreeSwift trees to various file formats.
241

242
```python { .api }
243
def write_tree_newick(self, filename: str, hide_rooted_prefix: bool = False) -> None:
244
    """
245
    Write tree to Newick format file.
246

247
    Parameters:
248
    - filename (str): Output filename (plain-text or .gz for gzipped)
249
    - hide_rooted_prefix (bool): Whether to hide rooted prefix in output
250
    """
251

252
def write_tree_nexus(self, filename: str) -> None:
253
    """
254
    Write tree to Nexus format file.
255

256
    Parameters:
257
    - filename (str): Output filename (plain-text or .gz for gzipped)
258
    """
259

260
def newick(self) -> str:
261
    """
262
    Get Newick string representation of tree.
263

264
    Returns:
265
    - str: Newick format string
266
    """
267
```
268

269
Usage examples:
270

271
```python
272
import treeswift
273

274
# Create or load tree
275
tree = treeswift.read_tree_newick("(A:0.1,B:0.2,C:0.3);")
276

277
# Write to Newick file
278
tree.write_tree_newick("output.nwk")
279

280
# Write to gzipped Nexus file
281
tree.write_tree_nexus("output.nexus.gz")
282

283
# Get Newick string
284
newick_str = tree.newick()
285
print(newick_str)
286

287
# Write with custom options
288
tree.write_tree_newick("output_unrooted.nwk", hide_rooted_prefix=True)
289
```