TREE_DOCTOR(1)

💖 TREE_DOCTOR — okay bestie, let's talk trees ✨

so this is tree_doctor, a User Commands girlie, and she is literally the tree surgeon of your phylogenetic dreams. no cap.

---

🌸 NAME 🌸

tree_doctor — scale, prune, merge, and otherwise tweak phylogenetic trees. she does it all, she's that girl 💅

---

🦋 DESCRIPTION 🦋

Scale, prune, merge, and otherwise tweak phylogenetic trees. that's the whole vibe.

okay so here's the thing you need to know before you hand her a file: by default she expects the input to be a tree model (.mod) file. unless the filename ends with .nh, or you've passed the -n option — in which case she's expecting a tree file in Newick format instead. choose your fighter, basically. 🙈

---

🎀 USAGE 🎀

tree_doctor [OPTIONS] <file.mod>|<file.nh>

---

✨ OPTIONS ✨

she has so many options and honestly? iconic behavior.

• --prune, -p <list> — remove all leaves whose names are in the given list (comma-separated, bestie, commas matter 💀), then remove nodes and combine branches so it's restored as a complete binary tree again (aka every node has either zero children or two children, no in-between nonsense). 🚨 heads up: this option runs before all the other options. she's first in line, she has main character energy.
• --prune-all-but, -P <list> — exactly like --prune, but instead of removing the ones you list, she removes all the leaves except the ones you specified. the flip side, the inverse, the remix. 🌈
• --get-subtree, -g <node_name> — also like --prune, but she removes all leaves who are not descendants of node. (📝 note: this implies --name-ancestors if the given node isn't explicitly named in the input tree.)
• --rename, -r <mapping> — rename leaves according to the given mapping. the format of <mapping> must be:

"oldname1 -> newname1 ; oldname2 -> newname2 ; ..."

and this one runs after all the other options, so the old names are what get used for --prune, --merge, etc. don't get it twisted. 🫶

• --scale, -s <factor> — scale all branches by the specified factor. multiply, glow up, done.
• --name-ancestors, -a — make sure names are assigned to all ancestral nodes. if a node is unnamed, she creates a name by concatenating the names of a leaf from its left subtree and a leaf from its right subtree. she's naming her children after both sides of the family fr fr.
• --label-subtree, -L <node[+]:label> — add a label to the subtree of the named node. if the node name is followed by a + sign, then the branch leading to that node gets included in the subtree too. you can use this multiple times to add more than one label — but a single branch may have only one label, so no double-dipping. also: --label-subtree and --label-branches options are parsed in the order given, so later uses may override earlier ones. and labels get applied after all pruning, re-rooting, and re-naming options are applied. 💅
• --label-branches, -l <branch1,branch2,...:label> — add a label to the branches listed. branches are named by the name of the node which descends from that branch. see --label-subtree above for more info (she's not repeating herself, go look 👀).
• --tree-only, -t — output tree only, in Newick format, rather than the complete tree model. minimal, clean, she understood the assignment.
• --no-branchlen, -N — (implies --tree-only.) output only the topology in Newick format. just the shape, no numbers. silhouette challenge. 🦋
• --dissect, -d — instead of the ordinary output, print a description of the id, name, parent, children, and distance to parent for each node of the tree. sometimes useful for debugging. can be used with other options. she's being so transparent with you.
• --branchlen, -b — instead of the ordinary output, print the total branch length of the tree that would have been printed. a little sneak peek of what you almost got. 😭
• --depth, -D <node_name> — instead of the ordinary output, report the distance from the named node to the root.
• --reroot, -R <node_name> — reroot the tree at the internal node with the specified name. changing the whole perspective, honestly.
• --subtree, -S <node_name> — (for use with --scale) alter only the branches in the subtree beneath the specified node. local changes only, we respect boundaries. 🎀
• --with-branch, -B <node_name> — (for use with --reroot or --subtree) include the branch above the specified node with the subtree beneath it. bringing the plus-one. 💖
• --merge, -m <file2.mod> | <file2.nh> — merge with another tree model or tree. okay this one's long, stay with me bestie:

the primary model (<file.mod>) must have a subset of the species (leaves) in the secondary model (<file2.mod>), and the primary tree must be a proper subtree of the secondary tree — meaning the subtree of the secondary tree beneath the LCA of the species in the primary tree must equal the primary tree in terms of topology and species names. if a full tree model is given for the secondary tree, only the tree will be considered.

the merged tree model will have the rate matrix, equilibrium frequencies, and rate distribution of the primary model, but a merged tree that includes all species from both models. 🫶

the trees get merged by first scaling the secondary tree so that the subtree corresponding to the primary tree has equal overall length to the primary tree, then combining the primary tree with the non-overlapping portion of the secondary tree.

⚠️ and the names of matching species (leaves) must be exactly equal. no typos, no vibes-based matching. exact. periodt.

• --extrapolate, -e <phylog.nh> | default — extrapolate to a larger set of species based on the given phylogeny (Newick-format). the primary tree must be a subtree of the phylogeny given in <phylog.nh>, but it does not need to be a "proper" subtree (see --merge).

a copy gets created of the larger phylogeny, then scaled so that the total branch length of the subtree corresponding to the primary tree equals the total branch length of the primary tree; this new version is then used in place of the primary tree.

✨ and if you pass the string default instead of a filename? then a phylogeny for 25 vertebrate species, estimated from sequence data for Target 1 (CFTR) of the NISC Comparative Sequencing Program (Thomas et al., Nature 424:788-793, 2003), will be assumed. fancy.

this option is similar to merge but differs in that the branch length proportions of the output tree come completely from the larger tree, and the smaller tree doesn't have to be a proper subset of the larger tree.

• --newick, -n — the input file is in Newick format (necessary if the file name does not end in .nh). she needs the heads-up, okay?
• --help, -h — print this help message. 🫶

---

okay that's literally everything, she doesn't gatekeep 💜 go forth and doctor some trees bestie, slay 🌈⭐

---

and that's the whole page — this was tree_doctor version 1.4, dated May 2016, mwah, no notes 💅🎀✨