Skip to content

build_tree

piqtree.build_tree(aln, model, rand_seed=None, bootstrap_replicates=None, num_threads=None, other_options='')

Reconstruct a phylogenetic tree.

Given a sequence alignment, uses IQ-TREE to reconstruct a phylogenetic tree.

PARAMETER DESCRIPTION
aln

The sequence alignment.

TYPE: Alignment

model

The substitution model with base frequencies and rate heterogeneity.

TYPE: Model | str

rand_seed

The random seed - None means no seed is used, by default None.

TYPE: int | None DEFAULT: None

bootstrap_replicates

The number of bootstrap replicates to perform, by default None. If 0 is provided, then no bootstrapping is performed. At least 1000 is required to perform bootstrapping.

TYPE: int | None DEFAULT: None

num_threads

Number of threads for IQ-TREE to use, by default None (single-threaded). If 0 is specified, IQ-TREE attempts to find the optimal number of threads.

TYPE: int | None DEFAULT: None

other_options

Additional command line options for IQ-TREE.

TYPE: str DEFAULT: ''

RETURNS DESCRIPTION
PhyloNode

The IQ-TREE maximum likelihood tree from the given alignment.
Source code in src/piqtree/iqtree/_tree.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def build_tree(
    aln: Alignment,
    model: Model | str,
    rand_seed: int | None = None,
    bootstrap_replicates: int | None = None,
    num_threads: int | None = None,
    other_options: str = "",
) -> PhyloNode:
    """Reconstruct a phylogenetic tree.

    Given a sequence alignment, uses IQ-TREE to reconstruct a phylogenetic tree.

    Parameters
    ----------
    aln : Alignment
        The sequence alignment.
    model : Model | str
        The substitution model with base frequencies and rate heterogeneity.
    rand_seed : int | None, optional
        The random seed - None means no seed is used, by default None.
    bootstrap_replicates : int | None, optional
        The number of bootstrap replicates to perform, by default None.
        If 0 is provided, then no bootstrapping is performed.
        At least 1000 is required to perform bootstrapping.
    num_threads: int | None, optional
        Number of threads for IQ-TREE to use, by default None (single-threaded).
        If 0 is specified, IQ-TREE attempts to find the optimal number of threads.
    other_options: str, optional
        Additional command line options for IQ-TREE.

    Returns
    -------
    PhyloNode
        The IQ-TREE maximum likelihood tree from the given alignment.

    """
    validate_other_options(other_options, INVALID_BUILD_TREE_PARAMS)

    if isinstance(model, str):
        model = make_model(model)

    rand_seed = process_rand_seed_nonzero(rand_seed)

    if bootstrap_replicates is None:
        bootstrap_replicates = 0

    if num_threads is None:
        num_threads = 1

    names = aln.names
    seqs = [str(seq) for seq in aln.iter_seqs(names)]

    yaml_result = yaml.safe_load(
        iq_build_tree(
            names,
            seqs,
            str(model),
            rand_seed,
            bootstrap_replicates,
            num_threads,
            other_options,
        ),
    )
    return _process_tree_yaml(yaml_result, names, model)

Usage

For usage, see "Construct a maximum likelihood phylogenetic tree".