Phylogenetics

What the workbench is

Building a phylogenetic tree and drawing a publication figure of it are normally two separate chores with two separate kinds of friction. The first means remembering the exact incantation for MAFFT, trimAl, ModelFinder, and IQ-TREE, and the flags that go with them. The second usually means uploading your tree to a web service like iTOL and styling it there. The Phylogenetics workbench answers both, and it lives at /phylo, one click from the rest of the app.

Tree inference is not executed inside ResearchOS. The Tree Builder generates version-pinned commands and an environment file for you to run in an external environment you choose. Import the resulting tree into the Tree Studio to render, annotate, and export it locally. ResearchOS does have backend services for accounts and optional online features; they are not a tree-inference service.

The Tree Builder: a recipe, not a black box

The Tree Builder is a short wizard. You answer a handful of questions about your data and how you want to analyze it, and it writes you a complete, runnable recipe, the alignment step, the trimming step, the model selection, the tree search, and the support values, with every tool version pinned. It never runs the recipe. It gives you the commands and an environment file so you run them yourself and own the result.

The questions follow the real shape of a phylogenetics analysis. You pick whether your data is nucleotide or protein, then which of three analyses you are doing. A single locus takes one gene or region to one tree. A concatenated supermatrix joins many genes into one partitioned alignment and infers a single maximum-likelihood tree. A coalescent species tree builds a tree per gene and summarizes them with ASTRAL, which accounts for the way individual gene histories disagree. From there you choose the aligner (MAFFT by default, with MUSCLE and Clustal Omega as alternatives), the trimming step (trimAl, ClipKIT, or Gblocks, or none), how the substitution model is chosen, the inference tool, and how branch support is measured.

Model selection. By default the recipe uses ModelFinder, which tests candidate substitution models against your alignment and picks the best-fitting one, so you do not have to guess. If you already know the model you want, a searchable picker lets you fix it instead, and the recipe passes it straight through.

Support values. The default is the ultrafast bootstrap with 1000 replicates plus an SH-aLRT test, the modern standard for IQ-TREE. You can switch to the slower standard bootstrap, or turn support off for a quick look. An advanced section exposes the dials a phylogeneticist actually reaches for, the bootstrap replicate count, the -bnni correction, ascertainment-bias correction for SNP data, restricting ModelFinder to a common model set, the thread count, and an outgroup to root on.

What you get out

The Builder produces three things that fit together. A recipe of shell commands, each with a one-line comment explaining what it does, that you copy and run. An environment file (environment.yml) that pins every tool to a specific version through conda, so the run is reproducible and so installing the tools is one command. And install steps for your operating system, conda-first on macOS, Windows, and Linux, because that is the honest cross-platform path for bioinformatics tools. The point is that you can hand the recipe to a labmate, or to your future self, and get the same tree.

The Tree Studio: render and annotate, no upload

The Tree Studio is the free answer to iTOL. You open a tree, and it draws, styles, annotates, and exports it entirely in your browser. There is no tree upload required for rendering, which is computed in the page rather than by a plotting service.

It reads the standard tree formats, Newick and Nexus, whether you paste the text, open a saved tree from your library, or drop in the .treefile the Tree Builder recipe produced. The Tree Builder wizard is reachable from the rail's Build a tree overlay button rather than a top-level toggle.

The collection rail

A collapsible left rail lists every tree you have saved, newest first, with a search field to filter by name. Clicking a tree in the rail opens it in the canvas. A Build a tree button at the bottom of the rail opens the Tree Builder recipe wizard as a centered overlay, so you can kick off a new analysis without leaving the Studio.

The five action-rail tabs

When a tree is open, a tabbed rail on the right organizes every control into five tabs. Each tab is a flyout panel.

• Shape. Layout, rooting, axes, and the page frame. Pick one of six layouts: Rectangular, Slanted, Circular, Fan, Inward Circular, or Unrooted. Toggle between phylogram (branch lengths to scale) and cladogram (equal branch lengths). Toggle the branch-length scale bar, a root-edge stub, and a full-width time axis. Reroot on an outgroup, midpoint-root, ladderize, or rotate a clade by picking its tip members. Color branches by a metadata column using the Branch color by picker.
• Layers. The draw order from inner to outer. Each layer is an annotation track that you add from the Add menu and reorder by dragging. Tracks include tip labels, tip points, color strips, heatmap rings, bar panels, MRCA clade highlights, node pies, bracket annotations, and support-value labels on internal nodes.
• Data. Metadata (drop a CSV to drive the layers), alignment (drop a FASTA to show an MSA panel beside the tips), and a Data Hub plot picker (align a grouped-bar figure to the tips by a join column). The tab shows live match counts for each source so you know how many tips lined up before you add a layer.
• Export. Download as SVG or PNG, copy the figure to the clipboard, export the page sheet (when the artboard is on), and save the current tree to your library. A Copy reference for a note button produces a ros:// link you can paste into any note to embed the tree as a live card.
• Code. Download Python to recalculate supported figure layers from editable tree and annotation inputs. A separate appearance export preserves saved drawing coordinates. The optional R scaffold covers only supported ggtree layers and lists its limitations.

Annotation tracks. A finished figure is rarely just the tree. The Studio layers the tracks a published phylogeny carries: tip labels, colored tip points, a color strip beside the tips, aligned bar charts, a heatmap panel, MRCA clade highlights, node pie charts, bracket annotations, and the bootstrap or posterior support on each branch. Each track is toggled on or off, so you build up exactly the figure you need.

Linking your metadata. The tracks are driven by a metadata table you link as a CSV in the Data tab, one row per tip with whatever columns you want to show, a clade assignment, a country, a resistance call, an abundance. Real tip labels are messy, often a strain name joined to an accession, so the match is robust. It tries an exact match first, then a normalized one, then a token match against composite labels, auto-detects which column holds the tip identifier, and shows you a live count of how many tips it matched, so you can see at a glance whether your table lined up.

MSA alignment panel

Drop an aligned FASTA in the Data tab and the Tree Studio adds an MSA panel beside the tips. Sequences join to tips by label using the same robust matcher as metadata. Long alignments are binned into blocks for readability; the match-count line shows how many tips have a sequence.

ZoomPanCanvas and minimap

The canvas pans and zooms with the same trackpad-native model the Data Hub and Figure Composer use: pinch or scroll to zoom at the cursor position, drag to pan. A minimap thumbnail appears in the corner when you are zoomed in, giving you a birds-eye view of the full tree with a rectangle showing the current viewport. Click or drag the minimap rectangle to jump to that region. A fit control snaps the tree back to fill the visible area, and a zoom readout shows the current scale.

Adding data straight from the Data Hub

Linking a CSV by hand is one way in. The Studio also finds the data for you. When you open a saved tree, it looks at the Data Hub tables in the same project, works out which ones share identifiers with your tips, and ranks them by how many tips each one covers. A quiet banner tells you when something fits, for example that a resistance table joins seven of your eight tips, and a Find data for this tree button is always there in the Layers panel.

Choosing one opens a short add-data wizard. You pick the table, pick the columns you care about, and for each column pick how it should read on the tree, where a numeric column can become a bar panel, a heatmap, dots, or sized points, and a categorical one becomes a color strip. The wizard adds them as real, editable layers in the stack, the same layers you would have built by hand, and you can loop back to add another table without leaving it. Every join rate and every available overlay is computed in the page, so what the wizard offers is always grounded in your actual data.

Exporting the figure

When the figure looks right, you export it as SVG for a vector you can drop into a manuscript or refine in Illustrator, or as a PNG for a slide, using the same exporter the Data Hub uses for its plots.

Download Python generates a Matplotlib script with editable TREE and SPEC inputs. Run it externally to recalculate supported layouts and data layers and write SVG, PDF, and PNG files. Unsupported options are reported before export, and font rendering can vary between computers. A separate rectangular-comparison script is available for supported comparison views.

Preserve the saved appearance exports a different Python script that redraws saved coordinates. It rejects changes to its included tree and annotation sources because those changes need recalculation.

The optional R scaffold is not a complete reproduction of the Studio figure. Supply your own tree.nwk andmetadata.csv; they are not bundled. Some layouts, panel types, palettes, and sizing are omitted or approximated. Review the figure-specific limitations shown in the Code tab before using it.

Trees alongside the rest of your work

A tree is an object in your folder like a note, a sequence, or a molecule, so it lives in the same connected workspace. A saved tree opens in the Studio by a deep link, and you can embed it in a note or experiment, where it renders as a live tree card rather than a flat screenshot, the same way a sequence or a molecule embeds. The writeup of an analysis and the tree it describes stay in one place. How embeds behave in a note is covered under the markdown editor.

Why you can trust the output

Two things on the transparency page back the workbench up. The first is that the Tree Studio's native layout is checked against ggtree, the de-facto standard tree-plotting package in R, on real published phylogenies, so the figure you draw here matches the one the standard tool draws. The second is published-tree reproduction, where we run the Builder's generated recipe on a real paper's own data and check that it recovers that paper's published tree.

What it is built on

The Tree Studio's layout and rendering are written natively in the app, with no plotting library doing the drawing, which is what lets it render in the browser with nothing to upload. The Tree Builder writes recipes for the standard open-source phylogenetics tools, MAFFT, trimAl, ClipKIT, Gblocks, ModelFinder, IQ-TREE, RAxML-NG, FastTree, MrBayes, AMAS, and ASTRAL, and pins them through conda so your run is reproducible. The ggtree code export targets ggtree and treeio. These projects, and the rest of the open-source software ResearchOS stands on, are credited on the open-source page.