Tree I/O and Parsing

def read_tree(input: str, schema: str) -> Tree | list[Tree] | dict[str, Tree]:
    """
    Read a tree from a string or file.

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

    Returns:
    - Newick: Tree object (single tree) or list[Tree] (multiple trees)
    - NeXML/Nexus: dict[str, Tree] with tree names as keys
    - DendroPy: Tree object
    - Linkage: Tree object or list[Tree] (if return_list=True)
    """

import treeswift

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

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

# Read multiple trees from Newick file
tree_list = treeswift.read_tree("multiple_trees.nwk", "newick")

def read_tree_newick(newick: str) -> Tree | list[Tree]:
    """
    Read tree(s) from Newick string or file.

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

    Returns:
    - Tree: Single tree object if input contains one tree
    - list[Tree]: List of tree objects if input contains multiple trees (one per line)
    """

import treeswift

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

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

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

# Read from gzipped file
tree = treeswift.read_tree_newick("tree.nwk.gz")

def read_tree_nexus(nexus: str, translate: bool = True) -> dict[str, Tree]:
    """
    Read tree(s) from Nexus string or file.

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

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

import treeswift

# Read from Nexus string
nexus_content = """
#NEXUS
BEGIN TREES;
    TREE tree1 = (A,B,C);
    TREE tree2 = ((A,B),C);
END;
"""
result = treeswift.read_tree_nexus(nexus_content)
tree1 = result["tree1"]
tree2 = result["tree2"]

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

# Access additional metadata
if "taxlabels" in result:
    print(f"Taxon labels: {result['taxlabels']}")

def read_tree_nexml(nexml: str) -> dict[str, Tree]:
    """
    Read tree(s) from NeXML string or file.

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

    Returns:
    - dict[str, Tree]: Dictionary with tree names as keys and Tree objects as values
    """

import treeswift

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

# Read from NeXML string
nexml_data = "<nex:nexml>...</nex:nexml>"  # NeXML content
trees = treeswift.read_tree_nexml(nexml_data)

def read_tree_dendropy(tree) -> Tree:
    """
    Create TreeSwift tree from DendroPy tree.

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

    Returns:
    - Tree: TreeSwift Tree object converted from DendroPy tree
    """

import treeswift
import dendropy

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

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

# Preserve rooting information
if dendro_tree.is_rooted:
    print("Tree is rooted")
else:
    print("Tree is unrooted")
    print(f"TreeSwift is_rooted: {ts_tree.is_rooted}")

def read_tree_linkage(linkage, return_list: bool = False) -> Tree | list[Tree]:
    """
    Read tree from SciPy linkage matrix.

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

    Returns:
    - Tree: Tree object from linkage matrix
    - list[Tree]: List of trees if return_list=True
    """

import treeswift
import numpy as np
from scipy.cluster.hierarchy import linkage

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

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

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

def write_tree_newick(self, filename: str, hide_rooted_prefix: bool = False) -> None:
    """
    Write tree to Newick format file.

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

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

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

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

    Returns:
    - str: Newick format string
    """

import treeswift

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

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

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

# Get Newick string
newick_str = tree.newick()
print(newick_str)

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