build_tree
Read-only
Build a phylogeny from aligned sequences — distance methods (NJ, BIONJ, FastME, UPGMA/WPGMA), parsimony, maximum likelihood, or Bayesian MCMC under a strict clock and coalescent prior — with branch support from a bootstrap, aLRT or aBayes, or, for the Bayesian method, clade posterior probabilities. Wire it downstream of align_sequences.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gamma | No | gamma shape for among-site rate variation in the DISTANCE correction; 0 disables. Not the ML +Γ, which is `ml_gamma_categories`. Advanced. | |
| model | No | distance/substitution model (ape's names). K80 is the engine's default; very divergent sequences need raw or JC69. | K80 |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| method | No | tree-building method; distance methods are fast, ML is the slowest and best-justified. Values: nj (Neighbor-Joining), bionj (BIONJ), fastme-bal (FastME (balanced)), fastme-ols (FastME (OLS)), upgma (UPGMA), wpgma (WPGMA), parsimony (Maximum Parsimony), ml (Maximum Likelihood), bayesian (Bayesian (MCMC)). | nj |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| ml_model | No | ML substitution model. Values: JC69 (JC69), F81 (F81), K80 (K80), HKY (HKY), TN93 (TN93), GTR (GTR). Only applies when method is ml, or when support_method is alrt or abayes or shalrt. Advanced. | GTR |
| ml_shape | No | α of the discrete-Γ distribution over site rates — lower means more rate variation between sites. The starting value when the shape is estimated, and the fixed value when it is not. Inert while `ml_gamma_categories` is 1, because one category has no spread. Only applies when method is ml, or when support_method is alrt or abayes or shalrt. Advanced. | |
| bootstrap | No | bootstrap replicates; 0 disables. Each replicate rebuilds the whole tree, so cost scales with it — 100 is the conventional minimum for a published tree and is the panel's default. Only applies when support_method is bootstrap. | |
| ladderize | No | order each node's children by clade size, so the drawing reads as a ladder. Changes the Newick's child order and nothing about the topology. Advanced. | |
| sequences | No | aligned sequences — wire align_sequences' rows here, or name library documents. | |
| fastme_nni | No | FastME refinement by nearest-neighbour interchange (ape's `nni = TRUE`). Only applies when method is fastme-bal or fastme-ols. Advanced. | |
| fastme_spr | No | FastME balanced refinement by subtree prune-and-regraft (ape's `spr = TRUE`). Only applies when method is fastme-bal. Advanced. | |
| ml_invariant | No | proportion of sites that never change; 0 disables. The starting value when it is estimated. Only applies when method is ml, or when support_method is alrt or abayes or shalrt. Advanced. | |
| bayesian_runs | No | independent runs (MrBayes nruns), seeded seed, seed+1, ...; 2 or more pools their samples and reports the average standard deviation of split frequencies and the PSRF. Only applies when method is bayesian. | |
| bayesian_seed | No | seed of the chain; the same seed and settings reproduce the same samples. Only applies when method is bayesian. Advanced. | |
| bayesian_temp | No | heating increment (MrBayes temp): chain j samples the posterior raised to 1/(1 + temp*j). Only applies when method is bayesian. Advanced. | |
| midpoint_root | No | root the result at its midpoint — a drawing convention, not evidence about where the true root is. Advanced. | |
| sh_replicates | No | RELL replicates behind `shalrt` — resamples the three fits' per-site log-likelihoods, not the alignment, so a replicate costs microseconds rather than a whole re-inference. PhyML uses 10,000. Ignored unless `support_method` is `shalrt`. Only applies when support_method is shalrt. Advanced. | |
| bayesian_clock | No | clock model: strict (one rate on every branch), ucln, the uncorrelated lognormal relaxed clock (each branch its own rate, mean 1, log-scale sd sampled under Exponential(mean 1/3), as BEAST's UCRelaxedClockModel), or none: an unrooted tree with free branch lengths under an Exponential prior and no coalescent (MrBayes' unconstrained model). Only applies when method is bayesian. | strict |
| bayesian_kappa | No | transition/transversion ratio for K80/HKY, held fixed. Only applies when method is bayesian. | |
| bayesian_model | No | substitution model for the Bayesian chain, its parameters held fixed for the run: base frequencies are the alignment's own for F81/HKY, and kappa is `bayesian_kappa` for K80/HKY. Values: JC69 (JC69), F81 (F81), K80 (K80), HKY (HKY). Only applies when method is bayesian. | JC69 |
| bayesian_shape | No | Gamma shape (alpha) for +G, held fixed for the run; smaller means more rate variation among sites. Only applies when method is bayesian. | |
| bootstrap_seed | No | seed for whichever resampling this run does — the bootstrap's replicates, or SH-aLRT's. The same seed always reproduces the same support values. Only applies when support_method is bootstrap or shalrt. Advanced. | |
| support_method | No | which branch support to attach. `bootstrap` resamples alignment columns and rebuilds the tree per replicate (uses `bootstrap`/`bootstrap_seed`). The three branch tests re-infer nothing: they score each internal branch against its two nearest-neighbour rearrangements under the ML model, three likelihood evaluations per branch instead of N whole re-inferences. `alrt` is the parametric test of Anisimova & Gascuel (2006), read against a mixture-of-chi-squares null, and it saturates at 99.985%. `abayes` is the Bayesian support of Anisimova et al. (2011). `shalrt` is the Shimodaira-Hasegawa-corrected variant (PhyML `-b -4`): the same three fits, but the gap is read against a null built by RELL-resampling their per-site log-likelihoods `sh_replicates` times from `bootstrap_seed` — slower than the other two, does not saturate, and usually more conservative. All three use `ml_model`/`ml_gamma_categories`/`ml_shape`/`ml_invariant` for the model, whichever `method` built the tree. Values: bootstrap (Bootstrap), alrt (aLRT), abayes (aBayes), shalrt (SH-aLRT). | bootstrap |
| bayesian_chains | No | Metropolis-coupled chains per run (MrBayes nchains; its default is 4): the extra chains sample a flattened posterior and swap states with the cold one, so a run can cross valleys a single chain cannot. Each chain costs a full chain's time. Only applies when method is bayesian. | |
| include_subject | No | also include the node's subject. | |
| bayesian_burn_in | No | iterations discarded from the start. Only applies when method is bayesian. | |
| ml_rearrangement | No | topology search moves for the ML fit. `nni` moves one subtree past its neighbour and stops at the first topology no single move improves, which is a local optimum. `spr` runs that first and then sweeps prune-and-regraft, which reaches trees NNI cannot — at a quadratic number of rearrangements per sweep rather than a linear one. `tbr` runs both and then sweeps tree bisection and reconnection, which cuts a branch and rejoins the two halves by any pair of their branches: the largest neighbourhood here, measured at 1,950 distinct topologies against SPR's 814 on an 18-taxon tree, so roughly 2.4x an SPR sweep. Ignored unless `method` is `ml` and `ml_optimise_topology` is on. Values: nni (NNI), spr (NNI, then SPR), tbr (NNI, then SPR, then TBR). Only applies when method is ml. Advanced. | nni |
| bayesian_clock_sd | No | where the relaxed clock's sigma (log-scale sd of branch rates) starts; always sampled. Only applies when bayesian_clock is ucln. Advanced. | |
| bootstrap_measure | No | which bootstrap statistic to report. `fbp` is Felsenstein's proportion: the share of replicates that carry this exact branch: a yes/no question per replicate, so one taxon landing elsewhere makes the answer no, which is why a well-supported clade can read near zero on a large tree. `tbe` is the transfer bootstrap expectation (Lemoine et al. 2018, Nature 556:452-456): 1 minus the average number of taxa that would have to move to turn a replicate's nearest branch into this one, over the branch's depth. TBE reads higher than FBP on the same replicates and the two are NOT interchangeable, so say which one a number is. Both read the SAME replicates, so `tbe` costs no extra inference. Only applies when support_method is bootstrap. | fbp |
| ml_optimise_rates | No | fit the substitution rates rather than holding the model's own. Only applies when method is ml. Advanced. | |
| ml_optimise_shape | No | fit the discrete-Γ shape rather than holding `ml_shape`. Costs a degree of freedom in AIC/BIC, and does nothing while `ml_gamma_categories` is 1. Only applies when method is ml. Advanced. | |
| pairwise_deletion | No | exclude a gapped site only from the pairs it is missing in, rather than from every pair. ape's default is off (complete deletion), which keeps distances mutually comparable but discards a column if ANY sequence has a gap there — turn this on for gappy alignments. | |
| bayesian_brlen_rate | No | with no clock: rate of the Exponential prior on each branch length (MrBayes brlenspr=unconstrained:exp(rate)); 10 means a prior mean of 0.1 substitutions per site. Only applies when bayesian_clock is none. Advanced. | |
| bayesian_iterations | No | Metropolis-Hastings proposals. Each rescores the alignment, so time grows with iterations x taxa x site patterns. Only applies when method is bayesian. | |
| ml_gamma_categories | No | discrete-Γ rate categories for the rate heterogeneity across sites; 1 disables it. Only applies when method is ml, or when support_method is alrt or abayes or shalrt. Advanced. | |
| bayesian_theta_shape | No | shape of the Gamma prior on theta. Only applies when method is bayesian. Advanced. | |
| bayesian_theta_start | No | starting theta of the chain (not a prior). Only applies when method is bayesian. Advanced. | |
| ml_optimise_topology | No | let the ML search move the topology. With this off the result is the Neighbor-Joining topology with ML branch lengths, and the engine says so in a warning. Only applies when method is ml. Advanced. | |
| bayesian_sample_kappa | No | sample kappa (K80/HKY) under MrBayes' Beta(1,1) prior on kappa/(1+kappa), starting from bayesian_kappa. Only applies when method is bayesian. | |
| bayesian_sample_shape | No | sample the Gamma shape under MrBayes' Exponential(1) prior instead of holding it at bayesian_shape (which becomes the start); needs bayesian_gamma_categories > 1. Only applies when method is bayesian. | |
| ml_optimise_invariant | No | fit the proportion of invariant sites rather than holding `ml_invariant`. Costs a degree of freedom in AIC/BIC. Only applies when method is ml. Advanced. | |
| bayesian_min_part_freq | No | a clade enters the split-frequency deviation only if some run sampled it at least this share of the time (MrBayes minpartfreq). Only applies when method is bayesian. Advanced. | |
| parsimony_rearrangement | No | parsimony topology search: `nni` hill-climbs by nearest-neighbour interchange, `spr` adds prune-and-regraft when NNI stalls (phangorn's own default), `tbr` adds bisect-and-reconnect when SPR stalls. Nested, not alternatives: each runs the cheaper moves first, because every NNI move is an SPR move and every SPR move is a TBR move. `tbr` searches the largest neighbourhood this tool offers — 1,950 distinct topologies against SPR's 814 on an 18-taxon tree — and rescores each candidate whole, where SPR scores incrementally, so it is markedly the slowest. Values: nni (Nearest-neighbour interchange), spr (Subtree prune-and-regraft), tbr (Tree bisection and reconnection). Only applies when method is parsimony. Advanced. | nni |
| bayesian_gamma_categories | No | discrete-Gamma categories for among-site rate variation (+G, each category its bin mean); 1 is equal rates. Only applies when method is bayesian. | |
| bayesian_sample_frequency | No | keep one tree every this many iterations after burn-in. Only applies when method is bayesian. Advanced. | |
| bayesian_theta_prior_mean | No | mean of the Gamma prior on theta = 4N mu, in substitutions per site. Only applies when method is bayesian. Advanced. | |
| bayesian_sample_frequencies | No | sample the base frequencies (F81/HKY) under a flat Dirichlet, starting from the alignment's own. Only applies when method is bayesian. | |
| ml_optimise_base_frequencies | No | fit base frequencies rather than holding them equal. Only applies when method is ml. Advanced. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gamma | Yes | the Pybus-Harvey gamma statistic: negative if branching clusters toward the root (an early burst), positive if toward the tips. A standard normal deviate under the constant-rate null — read it with `gammaP`, and only if `clockDeviationInBranches` is below 1 | |
| gammaP | Yes | two-tailed P for `gamma` against the constant-rate (pure-birth) null | |
| newick | Yes | the tree in Newick format | |
| bayesian | Yes | under `method: bayesian`: the chain (iterations, burn-in, samples, seed, acceptance per operator), the fixed model, the priors, mean / 95% HPD / ESS of log L, theta and root height, every clade's posterior probability (0..1), the commonest topologies and the highest-posterior state. Absent under every other method | |
| tipCount | Yes | number of tips (leaves) | |
| transfer | Yes | under `support_method: bootstrap` with `bootstrap_measure: tbe`: per branch, its clade (the smaller side), its depth, the mean transfer distance over the replicates and the support on 0..1. Absent under `fbp`, which puts its values on the tree and nowhere else | |
| warnings | Yes | what the method had to say about the data | |
| statistics | Yes | tree statistics: tips, height, total length, diameter, the branch-length distribution, Colless/Sackin imbalance, cherries, treeness, the Pybus-Harvey gamma with its two-tailed P, and the ultrametricity readouts gamma depends on (`isUltrametric`, `rootToTipSpread`, `clockDeviationInBranches`) | |
| distanceMap | Yes | that distance matrix as a heatmap | |
| branchSupport | Yes | under `alrt`/`abayes`: the measure, the model, the tree's log-likelihood, and per branch its clade, the two alternative log-likelihoods, the statistic and the support (a fraction, not a percentage). Absent under `bootstrap` | |
| distanceMatrix | Yes | the pairwise distance matrix the tree was built from | |
| clockDeviationInBranches | Yes | how far from clock-like the tree is, in MEAN BRANCH LENGTHS. `gamma` and any lineages-through-time reading assume an ultrametric tree; below 1 the raggedness cannot reorder a branching event, above it the statistic is partly rate variation and is not a diversification result |