The desktop viewer for phylogenetic figures worth publishing.
Archaeopteryx is a mature, offline application for visualizing, annotating, and analyzing phylogenetic trees — built for publication-quality figures. It reads phyloXML, Newick / New Hampshire (NH/NHX), and Nexus trees — including annotated BEAST / BEAST X output — and brings together integrated taxonomy and sequence annotation, protein-domain architectures, calendar and geologic time axes, and WYSIWYG vector (PDF / SVG / EPS) export.
→ cmzmasek.github.io/archaeopteryx · Download the latest release
Self-contained installers (macOS .dmg, Windows .msi, Linux .deb) bundle a
runtime — there is no Java to install.
Prefer the browser? Archaeopteryx.js is the online version: open a tree in any modern browser, nothing to install. It shares this viewer's file formats, "Color by" rules and node-data card, so a tree looks the same in both.
- Integrated annotation — pull UniProt / NCBI taxonomy, sequence data, and protein-domain architectures straight onto the tree.
- Calendar & deep time — tip-dated calendar axes for molecular epidemiology, and a full ICS geologic time scale for the fossil record.
- Publication vector export — WYSIWYG PDF / SVG / EPS from the same renderer that draws the screen; outline text, figure-grade by construction.
- Undo & provenance — every edit is undoable, and every tree-changing operation records what it did.
- Large trees, five layouts — rectangular (three orientations), circular, and unrooted, with tip-aligned annotation columns that ride into circular rings.
- Reads what you have — Newick, NHX, Nexus, phyloXML, plus Nextstrain / Auspice JSON, tip-dated labels, and BEAST intervals.
See File → Demo Trees in the app for pre-configured examples of each feature.
The easiest way to run Archaeopteryx is a native installer. Each one bundles its own Java 21 runtime, so there is nothing else to install — no separate Java needed.
Download the installer for your platform from the latest release:
https://github.com/cmzmasek/archaeopteryx/releases/latest
The apps are not code-signed or notarized yet, so each platform shows a first-launch security prompt (steps below). Getting past it once is enough.
There are two macOS installers — take the one that matches your Mac. If you are not sure which you have, open the Apple menu → About This Mac: a Chip line (Apple M1 … M4) means Apple Silicon, a Processor line means Intel.
- Download
Archaeopteryx-<version>-apple-silicon.dmg(Apple Silicon) orArchaeopteryx-<version>-intel.dmg(Intel), and open it. - Drag Archaeopteryx into Applications.
- On the first launch, right-click (or Control-click) the app and choose Open, then Open again — this clears macOS's "unidentified developer" warning. After that, launch it normally.
- Download
Archaeopteryx-<version>.msiand run it. It adds a Start-menu entry (and, optionally, a desktop shortcut) and lets you choose the install folder. - Because the installer is unsigned, SmartScreen may warn — click More info → Run anyway.
sudo apt install ./archaeopteryx_<version>_amd64.deb
(or sudo dpkg -i archaeopteryx_<version>_amd64.deb). Launch it from your
applications menu, or by running archaeopteryx.
Archaeopteryx has no server, and never will. It does not phone home and it collects nothing.
If you would like to be told when a new version is out, switch on Settings → Application → Check for Updates at Launch (it is off unless you turn it on). With it on, Archaeopteryx reads the public GitHub releases page of its own repository once, a moment after it starts, and compares the version number with the one you are running. If yours is older, the Help menu gains a quiet first line, New version available: x.y.z, which opens the releases page. If not — or if there is no network, or the check fails for any reason — nothing happens and nothing is reported. Nothing about you, your trees or your machine is ever sent: the request is a plain read of https://github.com/cmzmasek/archaeopteryx/releases, the same page you could open yourself.
Otherwise, just check the releases page now and then.
If there is no installer for your platform, or you prefer a single self-contained file, run the jar with your own Java.
1. Install Java — running the jar needs Java 21 or newer (a Java runtime
is enough; a full JDK also works). Check what you already have with
java -version; if it reports 21 or higher you are ready, otherwise install a
free OpenJDK build such as Eclipse Temurin
(e.g. brew install --cask temurin@21 on macOS,
winget install EclipseAdoptium.Temurin.21.JDK on Windows, or
sudo apt install openjdk-21-jre on Debian / Ubuntu).
2. Download the jar — the ready-to-run, self-contained forester.jar (every
required library is bundled inside it) lives in the source repository:
curl -L -o forester.jar https://github.com/cmzmasek/forester/raw/master/forester/java/forester.jar
3. Launch it:
java -jar forester.jar # or open a tree directly:
java -jar forester.jar mytree.xml
For very large trees, give the JVM more memory with -Xmx, e.g.
java -Xmx4g -jar forester.jar mytree.xml.
Don't have a tree handy? Archaeopteryx ships with a small gallery of example trees, each pre-configured to show off a capability — open one and it comes up already colored, banded, or laid out, no setup required.
Just launch Archaeopteryx and pick a tree from File → Demo Trees:
- Color Tips by Metadata — a tree colored by a categorical property
- Annotation Columns — tip-aligned color strips and a numeric heat-map
- Symbol Columns — tip-aligned shape marks: a present value draws a filled mark, an explicit "no"/absent value a hollow mark, and a missing value nothing (a binary presence/absence column); a categorical field becomes distinct colored marks. Pick the glyph (circle / square / diamond / triangle) per column
- Properties in Labels — a tree whose tips each carry six properties: two stay in the tip label, the other four become tip-aligned columns. One field, one role — which is what keeps a heavily annotated tree readable
- Protein Domain Architectures — multi-domain proteins drawn to scale as flat,
rounded, distinctly-colored boxes (a soft shadow, an optional glow); label the domains
on the boxes or gather them into a draggable, E-value-aware legend
(Settings → Layout → Domain labels). In circular and unrooted views the
architectures ride each tip's spoke as a concentric ring — the iTOL look — whenever
Radial Labels are on (auto-enabled when you show domains in a radial layout).
A domain needs a positive length (its
togreater than itsfrom) and both coordinates present; any that does not is skipped, and Archaeopteryx says how many it ignored once the file is open, rather than refusing the tree over an annotation - Bat Phylogeny (Taxonomy by Rank) — 34 bat species with common + scientific names + synonyms, every clade rank-annotated, colorized by family (all offline)
- Animal Tree of Life (Nested Clade Levels) — 25 animals from sponges and comb jellies to the mammals, with three ranks annotated at once (order inside class inside phylum) as nested bars whose colours are shades of the phylum they sit in
- GTDB Taxonomy (Genome-based) — Bacteria + Archaea genomes with the GTDB classification imported from a GTDB-Tk table and colored by phylum (all offline)
- Ancestral State Pies — a discrete geographic trait as posterior pies
- Node Age Spindles — divergence-time uncertainty (point age + 95% HPD) as tapered spindles
- Tree Properties — a small gene family whose Tree Properties window (View menu, ⌘I) has something in every section: editable name, description and metadata, then structure, branch-length and support-value statistics with histograms, and a map of which tips carry taxonomy, sequences, dates and properties
- Break Long Branches — a fast-evolving outgroup on a huge branch drawn shortened with a break mark so the ingroup reclaims the width (with support values)
- SARS-CoV-2 Time Tree — a tip-dated viral tree on a calendar-year axis
- Phylodynamics (Nextstrain JSON) — an Auspice v2 dataset with geographic
ancestral-state pies, read straight from
dataset.json - Filoviridae (Ebola & Marburg) — a real filovirus phylogeny colored by species, with host/country/year metadata and per-protein accessions
- Dinosaur Time Tree — a dated archosaur tree (with Archaeopteryx!) on the geologic time scale
- Late Cretaceous Dinosaurs — an all-extinct clade narrow enough that the geologic axis drops a rank and bands the Late Cretaceous over its stages
- Lagomorph Time Tree — the rabbits, hares and pikas (18 living species back to the Eocene) on the geologic time scale
- Ammonite Time Tree — an all-extinct fossil clade with FAD/LAD range bars
- Tree of Life (Deep Time) — a time-calibrated tree back to LUCA (~3.8 Ga)
- Tanglegram — two trees (gophers vs. their lice) compared side by side
The demos are bundled inside the jar, so they are always available. (The same
trees, plus more, live in
forester/demo/
in the source repository for browsing on GitHub.)
Every button in the control panel on the left is a drawn icon rather than a word — one click each, no dialog, and the picture stays readable at any font size. The three things you change most often sit at the top.
Theme. A single sun / moon button switches between the light and dark themes. It always shows the theme it will switch to: a moon while you are in the light theme, a sun while you are in the dark one. The tree canvas follows the theme, and the choice is remembered between sessions.
Layout — the five display types. One row of five buttons, one exclusive group, covering every way Archaeopteryx can draw a tree:
| button | layout |
|---|---|
| tree pointing right | rectangular, root at left (the classic view) |
| tree hanging down | rectangular, root at top |
| tree growing up | rectangular, root at bottom |
| open ring with spokes | circular |
| free-form star | unrooted |
Layout family and root position are one question, so they are one control: any layout is a single click from any other, and there is no hidden "which orientation do I come back to?" state. All five are first-class — annotation columns, clade bands, time axes, HPD and range bars, tip images and the vector exports all work in every one of them.
Phylogram / cladogram. A row of three buttons, each drawn as a small tree with its tip labels, because the labels are where the difference actually shows:
| button | what it draws |
|---|---|
| ragged branches, ragged labels | phylogram — branch lengths to scale, so the tips end ragged |
| ragged branches, labels in a column | aligned phylogram — the same tree, with every tip label carried out to a common column |
| flush branches, labels in a column | cladogram — topology only; branch lengths ignored, all tips flush |
The aligned view needs somewhere to pin the labels — the common right-hand column in the rectangular layouts, the outer ring in circular — so it is unavailable (and greyed out) in the unrooted layout, which has neither. Your choice is remembered per tab and comes back when that tab leaves unrooted. All three are disabled for a tree without branch lengths, which can only be drawn as a cladogram.
Rectangular style. How a branch joint is drawn is a separate, set-once choice under Settings → Layout → Rectangular style: Square (right-angle elbows, the default), Euro Type (a slanted corner), Rounded (a curved corner) or Triangular (clades drawn as triangles). You can set it at any time — picking a style while a circular or unrooted tree is on screen does not switch the layout; it takes effect the next time you choose a rectangular one.
Zoom, fit and navigate. Below those sit the action buttons:
| button | what it does |
|---|---|
| Y+ / Y− | zoom in / out vertically |
| X− / X+ | zoom in / out horizontally |
| label rows pushed apart | expand the tree along the label axis until the labels stop overlapping at the current font size (Alt+E) |
| square frame with arrows | fit the whole tree into the window (Alt+C, Home or Esc) |
| landscape frame with arrows | fit to the window width, keeping the current vertical zoom (Alt+W) |
| small ladderized tree | ladderize the whole tree; click again to flip the direction (Alt+O) |
| arrow into a bar | back to the complete tree from a sub-tree (Alt+Shift+R) |
| plain left arrow | up one level towards the complete tree (Alt+R) |
| triangle with tip lines | uncollapse all collapsed clades (Alt+U) |
Several of these change with the layout, so the picture always matches what the click will actually do:
- Root at top / bottom. The fit-to-width frame turns portrait: it becomes fit to the window height, which is the same operation measured across the tree's breadth. The expand glyph's label rows turn with it.
- Circular and unrooted. The two zoom axes collapse into one, so X− / X+
are free and become rotate counter-clockwise / clockwise (the same as the
AandSkeys, orShift+mousewheel). The fit-to-width button becomes a node-label direction toggle — labels riding the spoke, or lying flat — and, like the theme button, it shows the state it will switch to. Expand is greyed out, since spreading labels apart has no meaning in a fan.
A button that cannot do anything right now fades rather than vanishing: the two sub-tree arrows stay dim until you are inside a sub-tree, and uncollapse-all until something is collapsed, so the row never changes shape under you.
The expand button is the deliberate alternative to Auto-hide Labels (in Display Data, on by default), which drops labels when a tree is drawn too densely to show them all. Expanding the tree until they fit means nothing has to be hidden — worth doing before an export, since a figure exported while labels are being auto-hidden is missing them, and the export report says so.
Which node am I on? Point at a node and a soft glow marks it. The cursor already tells you that something is clickable; the glow tells you which node — which is what you actually need on a dense tree, and most of all in the modes that reroot or delete. It appears in every Click on Node to: mode, including over a collapsed clade's triangle. Pausing there also brings up the node card with the node's data.
There is only ever one circle on the node, and its colour says what a click will do:
| glow | meaning |
|---|---|
| the node's own colour, else a neutral accent | you are on this node (any mode that is not a selection mode) |
| the found colour | in Select Node(s), a click will add this node |
| muted grey | in Select Node(s), a click will remove it |
Outside the selection modes the glow takes the colour the node is already drawn in — its Color by value, a node style you gave it, an event colour, a colorized clade — so the mark reads as belonging to that node instead of dropping an unrelated colour on top of it. A node with no colour of its own keeps the neutral accent. In Select Node(s) the colour means something (see the table), so there it stays as it is.
Pointing at a branch in Select Node(s) glows its clade root and marks the tips the click would take, since one circle cannot stand for forty of them. Over a collapsed triangle the glow reflects the whole clade, because a click there takes the tips hidden inside it rather than the clade root.
The glow is on-screen guidance only — it never appears in an exported figure.
The Color by: dropdown in the left control panel colors every tip by one of
the tree's fields — the taxonomy fields (code, scientific name, common name),
the sequence fields (name, symbol, gene name), or any node property the tips
carry (host, country, year, …). A categorical field gets one color per
value; a numeric field gets either individual colors or a color gradient (see
below). The same rules, ids and labels are used by
Archaeopteryx.js, so a shared
tree colors identically in both viewers.
A tree opens already colored. On open, Archaeopteryx picks the tree's most informative well-covered field and applies it — nothing to configure. The dropdown lists every usable field best first (how much of the tree a field covers, and how informatively it splits it); a sparse field — one covering only some of the tips — is offered at the end of the list but never chosen for you. A figure saved with the tree keeps its own coloring, and a field you chose yourself is never overridden. To open trees uncolored, switch off Settings → Labels & Colors → Auto-color a newly opened tree.
The legend is a draggable card (double-click it to send it back to its
corner). Each row shows the value's color and its tip count; [by count] /
[A-Z] flips the order, and long legends show the top 20 with a show all
control. When some tips carry no value for the field, a dashed-circle
"no value" row — pinned last — counts them, so partial coverage is visible
at a glance (those tips draw no color dot). Clicking a value row lets you
assign that value your own color; Use Automatic Color returns it to the
automatic one.
Numeric fields. A field with up to ten distinct numbers is treated as codes
(think H5N1 vs H5N2 subtype numbers) and gets individual colors; with more
values it becomes a color gradient (years, rates). For fields with up to
twenty distinct values a [colors] / [gradient] control in the legend lets
you flip between the two readings.
Values are grouped for coloring — spelling variants (Human / human /
homo_sapiens), a host value's qualifiers after ; and a country value's
subdivision after : (USA:CA = USA:IL), and a short dictionary of
unambiguous common-animal synonyms (swine / porcine / Sus scrofa all
read Pig; bovine / cattle → Cow; Homo sapiens → Human; …)
share one color and one legend row. This is display grouping only: the values
stored in your tree are never modified, and search, exports and the node
dialog always show them verbatim. Coloring by the taxonomy or sequence fields
themselves uses the values exactly as written, with no grouping at all.
Colors are stable. A value keeps its color while you dive into subtrees, collapse clades or delete nodes — the legend re-derives to what is on screen, but nothing recolors, so a subtree figure matches the whole-tree figure. (Gradients are the exception by design: a gradient always spans the visible range.) Switching the palette (Settings → Labels & Colors, Default or Colorblind-friendly) or Reset to Defaults re-assigns from scratch.
Size by works alongside: it scales each tip symbol by a numeric field, so one symbol can encode a color (field A) and a size (field B) at once.
A tree's tips often carry a lot more than a name — a host, a country, a clade, a
collection year, an accession, a passage history. Archaeopteryx reads all of it
(from phyloXML <property> elements, from File → Import Annotations, from a
BEAST or Auspice file) and gives you one place to decide how each field is shown:
Tools → Annotation Fields….
The rule is simple: each field gets exactly one role. It is a tip-aligned column, or it is part of the node's label, or it is not drawn. That exclusivity is the whole point — the fields that carry the figure become columns, and only the one or two that belong next to the name stay in the label. Ten fields crammed into a label is unreadable; ten thin colour strips beside the tips is a figure.
| "Show as" | what it draws |
|---|---|
| Color strip | a filled cell per tip, coloured by the value's category |
| Symbol | a centred glyph — filled when the value is present, hollow when it is explicitly no/absent/0/false, nothing when it is missing. Pick circle / square / diamond / triangle per column |
| Heat map | a filled cell coloured by the value's position in the numeric range |
| Heat map (matrix) | as above, but every matrix column shares one colour scale and one legend, drawn as a contiguous grid — the clustergram look |
| Bar | a horizontal bar whose length is the value's fraction of the range |
| Stacked bar | set several numeric fields to this and they merge into one segmented bar per tip — absolute lengths by default, or normalized to 100% |
| Pie | set several numeric fields to this and they merge into one pie per tip, each field a wedge |
| Text | the raw value, drawn as a column of text |
| In tip label | the value is appended to the node's own label |
Which roles you are offered follows the data. A numeric field gets the heat map / bar / stacked bar / pie set; a categorical one gets colour strips and symbols. A field that cannot usefully be coloured — one with the same value on every tip, or a different value on every tip, such as an accession — is offered as text or as label content, but not as a colour. And a field that only exists on internal nodes can only go in the label, because a tip-aligned column would have nothing to draw.
Label properties are drawn as values only, comma-joined, on one line — EPI1731, E3, not data:accession: EPI1731 data:passage: E3. The full list is always one
hover away in the node card, and in Display Node
Data, so narrowing the label costs you nothing.
The ↑ / ↓ buttons beside each field set the order — both the left-to-right order of the columns and the order the label reads in. Turning on any label field switches the Properties display checkbox on for you, so the choice takes effect immediately.
By default, a field that is not shown as a column goes in the label, which is what the Properties checkbox has always shown. Open the chooser and narrow it down from there. Settings → Reset to Defaults puts it back.
Everything here works in all five display types. In the circular layout the columns become concentric rings around the tree, and label properties ride each tip's spoke with the rest of its label.
A tree usually takes a while to turn into a figure: you pick a layout, switch some labels on and others off, add an annotation column or two, mark the clades, colour the tips by a field. All of that used to be lost the moment you saved the file and opened it again — the tree came back, the figure did not.
Now it comes back. When you save a tree as phyloXML, Archaeopteryx stores the figure alongside it and restores it when the file is reopened:
- the layout — rectangular (root left, top or bottom), circular or unrooted — and whether it is drawn as a phylogram, an aligned phylogram or a cladogram
- which labels are drawn: every checkbox in the Display panel, so a figure that shows only scientific names comes back showing only scientific names
- the annotation columns you configured, with their types and symbol shapes
- the clade marks, with their ranks and label angles
- colour by, size by, the ancestral-state pie trait, and the property fields you chose to show in the tip labels
Each tab keeps its own figure, so several trees can be open at once with quite different figures, and saving them all preserves each one.
Three things are worth knowing:
It only travels in phyloXML. Newick and Nexus have nowhere to put it. If you
want your figure to survive, save as phyloXML (.xml).
The theme is not part of it. Fonts, colours and light/dark stay your own preferences, so a figure you send a colleague opens in their setup rather than overriding it.
A figure from a newer version still opens. Anything an older Archaeopteryx cannot draw is skipped rather than refused, so the tree always opens.
Overlays are easy to add and, until now, tedious to remove: the clade marks in particular had no off switch once they were on. Tools → Clear All Overlays switches all of them off in one action — annotation columns, clade marks, colour by, size by, ancestral pies, and the properties shown in the labels.
It clears the overlays and nothing else. The layout stays as it is and the labels stay as they are, so this is a way to strip a tree back to a clean drawing without undoing the rest of your work.
Every node carries data beyond its name — taxonomy, sequences, branch support, a date, a distribution, a literature reference, properties — and two of the Click on Node to: modes open it in a window of its own. Display Node Data opens a read-only page; Edit Node Data opens the same page with every value live.
The page is one scrolling list of sections — Basic, Taxonomy, Sequences, Events (internal nodes only), Date, Distribution, Reference, Properties — each of which folds with a click on its header. Sections that hold data start open, empty ones start folded, and the read-only page shows only what is actually there. The header names the node and says what it is: external or internal, how many children and tips it has, its depth and its distance from the root.
A few things about editing are worth knowing:
- Nothing reaches the tree until you press Write to Tree (⌘↩ / Ctrl+Enter, or just Enter in any field). Type, change your mind, type again — the tree is untouched until then, and the title shows a • while there are unwritten changes. Close with unwritten changes asks whether to write them, discard them, or stay.
- Values are checked as you type. A branch length that is not a number, a taxonomy code that is not 3–5 capitals, a rank phyloXML does not know, a bad DOI or URL, a latitude outside ±90 — the field is outlined and the status line at the bottom says what is wrong. Write to Tree stays disabled until every field is valid, so a write is all-or-nothing.
- Only what you changed is written. A branch length you never touched keeps every digit it had; a sequence's annotations, a taxonomy's lineage, a distribution's polygons — data the editor does not show — survive a round trip untouched.
- A node can carry several sequences (a protein and its mRNA, say). Each is a card with its own name, symbol, gene name, type, accession, location, molecular sequence and URIs; + Add sequence adds a card, × removes one. The molecular sequence box counts its residues for you and cleans whatever you paste (line numbers, spaces) on write.
- Properties are a table — reference, value, unit, datatype, applies-to — with
+ Add property and − Remove property. References and units need a namespace
prefix (
data:depth,METRIC:m), and a value declaredxsd:decimalhas to be a number. This is the same data the Color by, Size by and annotation-column features read, so a property you add here is available to them at once. - Emptying a section removes it. Clear every taxonomy field and the node simply has no taxonomy any more, rather than an empty one.
- One write is one undo step, whatever you changed, and the tree's description records that the node was edited by hand.
Several node windows can be open at once. An undo or redo closes them, because the tree they were editing has been replaced.
View → Tree Properties… (⌘I / Ctrl+I, or double-click the tree's tab) opens the tree's own page in the same style as the node window. The top of it is editable: the tree's name (which is also its tab title), its description (free text — the tools append a sentence here whenever they change the tree), and the phyloXML metadata nothing else lets you set — an identifier with its provider, the tree type (gene tree, species tree, …) and the branch-length unit. The same rules as for node data apply: nothing reaches the tree until Write to Tree, a named tree cannot be renamed to nothing, a provider needs an identifier value, one write is one undo step, and closing with unwritten changes asks first.
Below that, everything the tree can tell you about itself, computed on the spot and kept current while the window is open:
- File — path, format (as sniffed from the file, not guessed from its suffix), size, when it was last modified, and whether there are unsaved changes.
- Structure — tips, internal nodes, branches, rooted or not, whether it is fully binary or how many polytomies it has, its depth, its height (the longest root-to-tip path), and how many clades are collapsed.
- Branch lengths — how many branches have one, median, mean ± sd, minimum, maximum, the total tree length, zero-length and negative branches, whether the tree is ultrametric — and a small histogram of the distribution (hover a bar for its range and count).
- Support values — one section per kind (bootstrap, posterior probability, …), each with the same statistics and its own histogram.
- Annotation coverage — the answer to "what is in this tree": how many tips carry a taxonomy (and a taxonomy identifier), how many distinct taxonomies there are, how many tips carry sequences, molecular sequences and domain architectures, dates, distributions, references, how many internal nodes are named, the event totals (duplications, speciations, gene losses), and every property name with the number of nodes that have it. This is also a quick way to see which tools will work on the tree: Color by needs properties, the taxonomy tools need taxonomies, and so on.
- Time axis — when the tree has dates or a time axis: the axis type, how many nodes are dated, the unit, and the root age or the most recent date.
One window per tab; opening it again brings the existing one forward. The statistics re-read the tree shortly after every change — an edit, an undo, a redo — and any edits you have typed but not yet written are kept.
View → as phyloXML / as Newick / as Nexus show the tree as text, in one window with a
format switcher at the top (all three items open the same window, on the format you asked
for). The text is what Save As would write — Newick and Nexus honour the support-value
setting under Settings → Files — with the markup muted so the names stand out: tags,
brackets, commas, branch lengths and support values in grey; the words that structure the
document in the accent colour (#NEXUS, Begin Taxa;, TaxLabels, Tree, End;) with
setting and attribute names such as NTax= or phyloXML's branch_length= in the same colour
but lighter; and the labels themselves in the normal text colour. Only the document's own
structure is tinted — a taxon that happens to be called End or Matrix stays plain data. Find (⌘F / Ctrl+F) highlights every hit
and steps through them with ↩ and ⇧↩; Wrap lines is on for the one-line formats and off
for phyloXML; Copy puts the whole text on the clipboard and Save As… writes it to a
file. The window re-generates its text after the tree changes.
Hovering a node shows a card with the essentials — name, distance to parent, date, depth, support values, taxonomy, each sequence's accession and symbol, events, properties, and for an internal node the number of tips below it — the same card, in the same order, as the online Archaeopteryx.js viewer. It follows the light or dark theme, keeps itself inside the window, and goes away the instant the pointer leaves the node. (It is drawn on the tree canvas itself, not as a separate window, so it can never be left behind on the desktop.) Switch it off with Display Data → Rollover in the control panel if you find it busy.
Edit → Undo (⌘Z / Ctrl+Z) steps back through the tree edits of the current tab; Edit → Redo steps forward again. Both menu items name the operation they will reverse — Undo Collapse Clade, Undo Edit Node Data — so you can see what you are about to change before you commit to it. Each tab keeps its own history, 25 steps deep.
Undo works by snapshotting the whole tree before each change rather than by knowing how to reverse each operation individually. That is why it covers everything uniformly: rerooting (including midpoint and MAD), ladderizing and ordering, swapping and deleting nodes or subtrees, cut and paste, node-data and tree-property edits, node styles and branch colours, collapsing and uncollapsing clades, and every data tool that writes into the tree — fetch, infer ancestor taxonomies, extract dates from labels, import annotations, import GTDB taxonomy, load alignment and write clade taxa. Gene-tree/species-tree reconciliation does not need it: it opens its results in a new tab and leaves your tree untouched.
Two things are deliberately outside it:
- Display settings are not tree edits. Which checkboxes are on, the layout, the colours you pick in a legend, which annotation fields are shown — none of these change the tree, so none of them consume an undo step. Settings → Reset to Defaults is what returns those to their starting state.
- Looking at something is never an edit. Opening a node in the editor and closing it again leaves the history untouched; only Write to Tree creates a step, and one write is one step no matter how many fields you changed before pressing it.
Open windows survive an undo. A node-data or Tree Properties window that is open when you undo or redo stays open and simply re-reads its node from the restored tree. Anything you have typed but not yet written is kept, and is now measured against the restored values, so you can still press Write to Tree. If the undo removes the node itself (you undo the step that added it, or redo a deletion), the window stays open but says so in its status line and can no longer write; the next undo or redo that brings the node back re-attaches it, edits intact.
Two independent search boxes on the left control panel (A and B) find and highlight matching nodes; a node matched by A (red), by B, or by both (teal) is shown in a distinct colour, so two searches can be compared at a glance. Search B’s colour is chosen under Settings → Labels & Colors → Found/Selected Colors — Electric Violet (default), Neon Magenta, or Emerald Green — each picked to stay legible on a white background, and the choice is remembered across restarts.
When both boxes carry a query, a Combine: control appears below them: keep the two highlights independent (the default), or fold them into one result set — A AND B (matches both) or A OR B (matches either) — which then drives the highlight, step-through, counter, and export.
Each box has two dropdowns — what to search and how to match — above its query field:
- Field — the node data to search. The list is tailored to the loaded tree, so
you only see fields it actually has, and the labels match the Display Data
checkboxes. Any Text (the default) searches every text field — and your custom
annotation properties — at once; or pick a specific one — Node Name, a taxonomy
field (Taxonomy Scientific, Taxonomy Common, Taxonomy Code, Taxonomy
Identifier, Taxonomy Synonym, Taxonomy Lineage), a sequence field (Seq
Name, Gene Name, Gene Symbol, Seq Accession), Annotation,
Domain, or any custom phyloXML property by its reference (e.g.
data:host). Numeric fields — Branch Length, Support / Confidence, and numeric properties — are offered as well, as are the tree's structure fields (prefixedStructure:): Clade Size (tips), Number of Children, Depth from Root (edges), Distance from Root (when the tree has branch lengths), and Node Type (leaf / internal / root) — so you can, for example, find every clade with more than 50 tips, or every unresolved node (children > 2). - Match — how the query is compared. For a text field: contains (the default), starts with, ends with, whole word, or regular expression. For a numeric field the operators switch to plain-language comparisons — equals, not equal, less than, at most, greater than, at least — and range (which reveals a second box for the upper bound).
When you search a specific text field, the query box suggests the values that
field actually has in the tree, filtered as you type — pick one to match it exactly.
This makes categorical fields (Node Type, Taxonomy Code, an annotation column
like data:host) point-and-click, and saves you from mistyping a value.
Two shared options sit above the boxes: Match Case and Inverse (select the
nodes that do not match). Within a text query, , is a logical OR and + a
logical AND (e.g. kinase, phosphatase, or human + receptor); both are treated
literally in a regular-expression search. Your field and match choices are remembered
as you work, so switching fields or navigating between trees doesn't reset them.
Step through the hits with the ◀ / ▶ buttons beside the boxes, or View → Find Next / Find Previous (⌘G / ⌘⇧G) — each jump centres the next match in the view. Under Settings → Labels & Colors, Bold Found Labels, Dim Non-Matches, and Pulse Found Nodes make the matches stand out further.
Whenever any nodes are highlighted, a Found / Selected: N counter appears at the right of the menu bar. Search hits and manual selection are one and the same in Archaeopteryx, so this is a single running total of the distinct highlighted nodes; it hides itself when nothing is highlighted. Hover it for the breakdown by search box (A / B) and manual Selected nodes.
Archaeopteryx treats a dated tree as a first-class object, and this is one of
the places it most tries to just work. However the dates arrive — parsed from
BEAST / BEAST X output, read from an Auspice / Nextstrain JSON,
extracted from the tip labels, or already sitting in a phyloXML <date> —
they all land in one native date model, and every time-tree feature reads from
it. So the whole toolkit composes on any dated tree, whatever its origin:
- Archaeopteryx auto-detects the dated tree, marks it with a "Time tree"
badge, and — because the axis is chosen per tree from its own
<date>values (their unit and magnitude) — draws the right axis automatically: a Geologic (ICS) axis for a tree dated in millions of years, a Calendar-year axis for a tip-dated molecular-epidemiology tree. A Dinosaur tree and a SARS-CoV-2 tree open in two tabs show the correct axis at the same time — there is no global switch to flip. - Node-age (HPD) bars / spindles draw each internal node's divergence-time uncertainty; fossil-range (FAD/LAD) bars draw each fossil tip's stratigraphic duration; Color by → date shades the tips by sampling date. Each turns on by itself when the tree carries the data for it.
Two things are worth knowing, because they are the rare places where the magic is conditional. A time axis is a property of a phylogram — it needs branch lengths that mean time — so a dated tree opens as a phylogram by default; if you switch it to a cladogram (the third button of the phylogram/cladogram row) the axis has no time scale to draw and steps aside. And a time axis replaces the plain numeric distance scale, so you see one or the other, not both.
Everything below is a piece of this one picture; in practice you rarely set any of it by hand.
Archaeopteryx reads the annotated trees produced by BEAST, BEAST 2, and BEAST X (the current BEAST 2 release line), including TreeAnnotator maximum-clade-credibility (MCC) summaries. Both output shapes are supported:
- annotated Nexus (TreeAnnotator's
.tree/.treesoutput), and - annotated Newick / NHX with FigTree-style
[&key=value, ...]comment blocks on nodes and branches.
Just open the file — parsing of these tags is on by default (toggle under Settings → Files → "Parse BEAST-style extended Newick/Nexus tags"). Each annotation is mapped onto the viewer's existing display features:
| BEAST annotation | Becomes | Turn it on with |
|---|---|---|
posterior |
Branch support (confidence) | Confidence Values; support coloring / symbols |
node age height / height_median / height_mean + height_95%_HPD={lo,hi} (or height_range) |
Node age with a 95% HPD interval | Node Age Bars (HPD) — auto-enabled on load for a dated tree with HPD intervals |
discrete / geographic traits (e.g. a phylogeographic location) with posterior state sets |
Ancestral-state pie charts | the "Ancestral pie:" dropdown (appears automatically when the tree carries such a trait) |
any other field (rate, length_*, custom traits, …) |
A node property beast:<key> |
Color by, Size by, and Annotation Fields (numeric traits render as gradients / bars) |
Nothing is discarded: recognized fields become native structures (support, node
dates, pies), and every remaining field is preserved as a beast:* property you
can color, size, or tabulate. A malformed field is skipped rather than aborting
the load, so real-world TreeAnnotator files open cleanly.
A dated MCC tree opens as a phylogram with Node Age Bars (HPD) already on, and — reading the dates' unit — draws the matching time axis on its own (a Calendar or Geologic axis; see Time trees & chronograms above). There is normally nothing to set by hand.
The node-age overlay has two shapes (Settings → Overlays → Data Overlays → Node age shape): a flat Bar across the 95% HPD interval (the FigTree convention), or a Spindle — a tapered lens that peaks at the point estimate and narrows to the HPD bounds, so you can see where the estimate sits within its interval. The spindle is a schematic of the summarized uncertainty (the point estimate + 95% HPD), not the raw posterior density — a summary (MCC) tree doesn't carry the per-node posterior sample.
Most molecular-epidemiology trees (BEAST, TreeTime, augur, GISAID Newick) carry
the sampling date in the tip name — hCoV-19/USA/CA-1234/2021|2021-03-15,
A/Texas/50/2012 — rather than as a structured field, so Archaeopteryx can't see
it. When you open such a tree Archaeopteryx offers to extract the dates
automatically; you can also run it any time from Tools → Extract Dates from
Labels…. Either way it recognizes ISO
(2021-03-15), numeric (15/03/2021), month-name (01-Dec-2015), decimal-year
(2021.37) and bare-year (…/2012) formats, shows a preview of exactly what
it found on every tip before writing anything, and (on Apply) sets each tip's
<date> plus a numeric data:date property. The tree then drops onto the
Calendar axis and gains a Color by → data:date date gradient.
An incomplete date maps to the midpoint of its interval (2021 → mid-2021); an
ambiguous numeric date (e.g. 05/03 — is that 5 March or 3 May?) is read
day-first by default, with a toggle in the preview. The write is undoable.
For a dated, time-calibrated tree — where the branch lengths are geologic time (millions of years) — Archaeopteryx can draw the international geologic time scale beneath the tree instead of a plain numeric axis. Turn it on under Settings → Overlays → Time Axis → Geologic (ICS). The axis appears when the tree is shown as a phylogram (branch lengths = time), as two coloured, named bands — System/Period over Series/Epoch — so a clade's position along the time axis reads directly against the named geologic intervals (Cretaceous, Jurassic, Triassic, …).
The Time Axis is per tree: Archaeopteryx reads the appropriate axis from each
tree's own <date> values (their unit and magnitude), so a geologic Dinosaur tree
in one tab and a calendar-dated SARS-CoV-2 tree in another each show the right axis
at the same time — no global switch to flip. The Settings dropdown lets you
override the axis for the current tab (or turn it off), and when you save the
tree, a deliberate choice travels with it (restored on reload).
The axis follows the layout: it runs along the bottom in the root-left orientation, down the breadth side in the root-on-top / root-on-bottom orientations, and becomes concentric coloured rings (period bands from the centre outward) in the circular layout — the iTOL-style geologic disc. (It is not shown in the unrooted layout, which has no single time axis to band.) In the rectangular orientations the axis stays pinned to the edge as you zoom and scroll, so it is always in view.
Beneath the coloured bands a numeric age axis is drawn — a ruler in millions of years before present (Ma), with tick marks and labels at round intervals that increase toward the root, so you can read any node's age directly off the axis. (In the circular layout the named, coloured annuli themselves are the age scale.)
The two bands adapt to the window the tree actually spans, so they always fully cover it and always carry some detail:
| The tree spans | Bands |
|---|---|
| one or two Series (e.g. an all-extinct Late Cretaceous clade) | Series/Epoch over Stage/Age |
| the Phanerozoic | System/Period over Series/Epoch |
| into the Proterozoic | Erathem/Era over System/Period |
| into the Archean | Eonothem/Eon over Erathem/Era |
So a billions-of-years "tree of life" is fully banded (the Precambrian is never blank), and — at the other end — a narrow window is not reduced to two enormous blocks: a tree that sits inside the Late Cretaceous is banded Late Cretaceous over Cenomanian, Turonian, Coniacian, Santonian, Campanian, Maastrichtian, which is the scale you actually want to read a Cretaceous tree against. Stages exist for the Phanerozoic only (the Precambrian has no ratified stages), which is exactly the range in which the axis can reach for them. The demo tree late-cretaceous-stages.xml (File → Demo Trees → Late Cretaceous Dinosaurs) shows it.
The tree is anchored in time by its root age: Archaeopteryx uses the oldest
<date> value in the tree, or you can set it explicitly with "Set root age…"
next to the Time Axis selector.
The axis is aligned to the tree's own branches, so it works on a fossil-only clade — one with no living (age-0) tip. Each Ma spans exactly one branch-length unit, anchored at the root age, so the coloured bands line up with the branch nodes and the youngest tips sit at their true age (e.g. an all-extinct ammonite tree ends at the end-Cretaceous, 66 Ma, rather than being stretched to the present). A tree that does reach the present is the ordinary special case.
Two optional refinements (both off by default, and — like the axis itself — per tree, saved with the tree) are available under Settings → Overlays when the geologic axis is on: Time-Axis Grid Lines draws faint reference lines across the tree at the finer band's interval boundaries (e.g. the Early/Middle/Late Triassic and the Triassic/Permian boundaries), and Geologic Boundary Ages labels the coarser band's boundaries with their age (e.g. 201.4 at the base of the Jurassic).
The interval names, boundaries, and official colours are those of the International Chronostratigraphic Chart of the International Commission on Stratigraphy (ICS / IUGS) (stratigraphy.org). Reference:
- Cohen, K.M., Harper, D.A.T., Gibbard, P.L. & Car, N. (2025, updated): "The ICS International Chronostratigraphic Chart this decade", Episodes 48:105–115.
For a tree of fossil taxa, a tip is not a single point in time — each taxon is
known from a stratigraphic range, from its First Appearance Datum (FAD, its
oldest occurrence) to its Last Appearance Datum (LAD, its youngest). Turn on
Settings → Overlays → Data Overlays → Fossil Range Bars (FAD/LAD) and, on a
dated phylogram, each tip that carries a <date> min/max gets a capped
stratigraphic-range bar spanning its known duration, drawn back over the terminal
branch so the tip label stays clear. Read against the Geologic time axis, this
turns a phylogeny into a proper stratigraphic-range figure — the duration and
overlap of taxa laid out against the named geologic intervals, no hand-drawing in
Illustrator required.
Like the Node Age Bars, it is auto-enabled on load when the tree has fossil tip
ranges, and it renders in every rectangular orientation and as radial segments in
the circular layout. The range is read from the tip's native phyloXML <date>
(value/min/max — the same model the node card and the node window show), so it works directly on a
tree time-scaled by any of the usual tools. Reference:
- Bell, M.A. & Lloyd, G.T. (2015): "strap: an R package for plotting phylogenies against stratigraphy and assessing their stratigraphic congruence", Palaeontology 58(2):379–389.
For a tip-dated tree — a time-scaled phylogeny whose branch lengths are calendar time and whose tips carry sampling dates, as in molecular epidemiology (e.g. a SARS-CoV-2 phylodynamic tree) — Archaeopteryx can draw a calendar-year axis instead of the geologic one. Turn it on under Settings → Overlays → Time Axis → Calendar (dates). It draws a labelled year/decade ruler (like the distance scale axis, but in calendar time): along the bottom in the root-left orientation, down the side in root-on-top / root-on-bottom, and as concentric labelled year rings in the circular layout.
The axis is anchored by the most-recent tip (the present): Archaeopteryx uses
the largest tip <date> (a calendar-year value) automatically, or you can set it
explicitly with "Set most-recent-tip date…" next to the Time Axis selector.
Each node's calendar date is then its distance-from-root back from that present.
The Time-Axis Grid Lines toggle (Settings → Overlays) also works here, drawing
faint reference lines across the tree at each labelled year tick.
Archaeopteryx reads Auspice / Nextstrain v2 datasets — the dataset.json
format behind nextstrain.org and the Auspice viewer,
the de-facto interchange format for dated, annotated pathogen phylogenies. Just
open a .json file with File → Read Tree from File… (or try File → Demo
Trees → Phylodynamics (Nextstrain JSON)).
The point is that it maps straight onto features Archaeopteryx already has, so your Nextstrain tree lights up on open:
num_date→ the tree is placed on the Calendar axis, and each internal node'snum_date.confidence(the divergence-time interval) becomes a Node Age spindle. It is also exposed as a numericnextstrain:num_dateproperty, so you can Color by the sampling date (a date gradient).div(cumulative divergence) drives a "Branch lengths: Time / Divergence" control (left panel, shown only for a tree that carries both) — flip the whole tree between the time layout (num_date, with the calendar axis) and the divergence layout (div, in substitutions/site) at any time. It's a reversible display mode: both metrics stay on the tree, so nothing is edited or lost.- every discrete trait —
country,region,clade_membership,host, … — becomes anextstrain:<trait>node property you can Color by, tabulate as an Annotation Column, or search; and each trait's per-node confidence drives the Ancestral-State Pies (geographic phylogeography, straight from the file).
Not imported (Archaeopteryx is a tree viewer, not a phylodynamics dashboard): the map, entropy, and frequencies panels. Reference:
- Hadfield, J. et al. (2018): "Nextstrain: real-time tracking of pathogen evolution", Bioinformatics 34(23):4121–4123.
Nested rank brackets down the side of a tree — genus inside family inside order — are one of the most common things in a published phylogeny figure, and one of the most commonly drawn by hand in Illustrator. Tools → Annotate Clades by Rank… builds them from the tree's own taxonomy.
Pick a rank and how to show it:
| Mode | What you get |
|---|---|
| Shaded boxes | a translucent wash behind each clade, in the clade's colour |
| Bars + labels | a solid colour bar per clade past the tip labels, with the taxon name |
Brackets ] + labels |
the same, drawn as a black-and-white bracket (no colour key) |
To take the marks off again, reopen the dialog and pick the first entry in the rank list — (none) — stop drawing the clade marks. It is offered only while there is something to remove, and it is never the entry the dialog opens on, so pressing OK can never wipe your annotation by accident. It removes the drawing only: any internal-node taxonomies you wrote with Also write the clade taxa into the tree are real tree data and stay put (undo them with ⌘Z). Settings → Reset to Defaults clears the marks too, along with everything else.
Bars and Brackets can show up to three ranks together, as nested columns. Choose the main rank, then add up to two more under Additional nested levels. You do not have to put them in any particular order — Archaeopteryx sorts them, always drawing the finest rank nearest the tips and the broadest outermost, which is the only arrangement in which the nesting reads correctly.
The colours are hue-banded: each clade at the broadest rank owns a slice of the colour wheel, and the finer clades inside it are shades of that slice. So in the animal demo, Mammalia, Aves and Amphibia all read as greens because they sit inside Chordata, while Insecta is a yellow inside olive Arthropoda — you can see which class belongs to which phylum without consulting the legend. Give a single rank and you get the plain distinct-colour palette instead, since there is no hierarchy to show.
Containment is read from the tree, not from the names: a genus belongs to the family whose clade root is its ancestor. That keeps the colouring honest when the taxonomy is patchy — a clade whose broader rank could not be resolved has no parent hue to vary, and is drawn desaturated rather than being given a confident colour implying a parent it does not have.
Two practical notes:
- Label angle is per level. Each level has its own Labels: Vertical / Diagonal / Horizontal setting. Vertical is the most compact and is usually right for a rank with a few large clades; Horizontal is the one to use when a rank has many clades of one or two tips each, because a vertical label needs far more height than a one-tip bar and a column of them will overprint. Horizontal costs width instead — three horizontal columns is what the animal demo uses.
- Skip single-member clades (on by default) suppresses the bar for a taxon represented by a single tip, which is usually just noise. Turn it off for a deep backbone like the animal demo, where many classes and orders legitimately have one representative and skipping them leaves the inner columns full of holes.
The legend splits into a titled block per rank, so a family row is never mistaken for a genus row, and every rank keeps rows even when one of them has far more taxa than the others. Clicking a legend row recolours that taxon, at its own rank.
Clade annotation draws in the three rectangular orientations and in circular, where the bars become concentric rings around the tree. It is not drawn in the unrooted layout: unrooted tips sit at different radii, so there is no common edge to hang a bar or bracket on, and a clade's tips are not guaranteed to occupy one contiguous sector.
Boxes stay single-level by design. The wash is translucent, so nesting one inside another would paint the inner clade as the product of two washes — darker than either, and no longer the colour its legend row claims.
Everything works offline whenever the tree itself carries the ranks (as the bundled demos do); otherwise Archaeopteryx offers to resolve the unplaced tips online through NCBI and UniProt. You can also tick Also write the clade taxa into the tree to turn the annotation into real, saveable internal-node taxonomies (that part is undoable).
Try it with File → Demo Trees → Animal Tree of Life (Nested Clade Levels), which opens with all three ranks drawn, or Bat Phylogeny (Taxonomy by Rank) for the single-rank case inside one order.
For trees of bacterial and archaeal genomes, Archaeopteryx imports the GTDB
(Genome Taxonomy Database) classification — the genome-based standard for microbial
taxonomy. Load a tree whose tips are genome accessions, then File → Import GTDB
Taxonomy… and pick a GTDB-Tk-style table (a tip-name column plus a GTDB
classification column, e.g.
d__Bacteria;p__Pseudomonadota;…;g__Escherichia;s__Escherichia coli, exactly as a
GTDB-Tk classify summary emits). Or just try File → Demo Trees → GTDB Taxonomy
(Genome-based).
Each of the seven standardized ranks — domain / phylum / class / order / family /
genus / species — becomes a categorical gtdb:<rank> node property, plus a
<taxonomy> at the most specific rank present. So you can immediately Color by
gtdb:phylum (or gtdb:domain), add an Annotation Column for gtdb:family, and
search gtdb:genus. It is entirely offline — no network lookup, no bundled
database — so it is reproducible and version-pinned to whatever GTDB release produced
your table. The import is undoable.
References:
- Parks, D.H., Chuvochina, M., Rinke, C., Mussig, A.J., Chaumeil, P.-A., Hugenholtz, P. (2022): "GTDB: an ongoing census of bacterial and archaeal diversity through a phylogenetically consistent, rank normalized and complete genome-based taxonomy", Nucleic Acids Research 50(D1):D785–D794.
- Chaumeil, P.-A., Mussig, A.J., Hugenholtz, P., Parks, D.H. (2020): "GTDB-Tk: a toolkit to classify genomes with the Genome Taxonomy Database", Bioinformatics 36(6):1925–1927.
Show a picture at each tip — a species photo, a phylogenetic silhouette, a specimen image — drawn right at the branch end, so a figure carries its own visual key. Turn it on with Settings → Overlays → Tip Images, and set the size with the slider next to it (a fixed height in pixels; the aspect ratio is preserved).
Each image comes from a reference attached to the tip. Two forms are auto-detected:
- a local file — a relative path (resolved against the folder the tree was loaded
from) or an absolute path, e.g.
images/t_rex.png; - an http(s) URL — fetched once, off the main thread, and kept in a small on-disk
cache (
~/.archaeopteryx/image-cache), so re-opening a tree of web images is instant and works offline afterwards.
The reference is read from a node property (image, img, photo, silhouette,
picture, thumbnail, tip_image, or image_url), from a taxonomy <uri> of type
image_url, or from any property whose value ends in a raster-image extension
(.png, .jpg, .jpeg, .gif, .bmp — SVG is not yet supported). The everyday way
to attach it is the raw tree plus a spreadsheet: keep an image column in your CSV/TSV
and load it with File → Import Annotations. A tree that already carries image
references turns Tip Images on automatically when you open it.
Tip images render in all five display types — rectangular (root left / top / bottom) and, drawn upright on the spoke, circular and unrooted — and appear in every export (PDF, SVG, EPS, PNG). A reference that cannot be loaded (a missing file, or a URL that points at a web page rather than the image itself) draws a faint broken-image marker so the problem is visible rather than silent.
Wikimedia Commons tip: a Commons article URL (
…/wiki/File:…) returns a web page, not an image. Use a direct-file URL such ashttps://commons.wikimedia.org/wiki/Special:FilePath/<FileName>, which redirects to the image file itself.
Show a multiple sequence alignment beside the tree — the classic tree + alignment figure. Load an aligned FASTA with File → Load Alignment (FASTA)…; each row is joined to the tip of the same name and drawn as a track of colored residue cells to the right of the labels. A tree saved as phyloXML embeds the alignment (it is written onto each tip's molecular sequence), so a re-opened tree shows its alignment automatically — and a tree that already carries aligned sequences turns the display on when you open it.
You can also open a Nexus file that bundles a tree and a sequence matrix in one file (a
CHARACTERS or DATA block of protein/DNA/RNA, as produced by MrBayes, PAUP*, and similar
tools). Just open it with File → Read Tree from File…; the matrix rows are joined to the
tips by taxon name and the alignment shows beside the tree automatically — no separate step.
Interleaved matrices, MATCHCHAR (.) shorthand, [ ] comments, and taxon names that
differ only in case or in _-vs-space between the tree and the matrix are all handled.
- Coloring follows the residue: a Zappo-style scheme for amino acids and an A/C/G/T-U scheme for nucleotides (auto-detected). At a wide enough column width the residue letter is drawn in each cell; gap positions show a faint dash.
- A dedicated scrollbar below the alignment pans the columns while the tree and its labels stay in place, so a long alignment stays navigable.
- Faint boundary lines mark the true start and end of the alignment, so a scrolled-into window is distinguishable from the real edges.
- A column ruler below the alignment shows absolute 1-based column numbers, so you can read exactly which columns a scrolled window is showing.
- Hover a residue for a readout of what is under the pointer (see below).
Point at any residue and a small readout tells you what it is:
| line | what it means |
|---|---|
| Alignment column | the 1-based column of the alignment — what the column ruler shows |
| Residue n of this sequence | the residue's own 1-based number in that sequence with the gaps removed |
L – Leucine |
the letter and its full name (for DNA/RNA, the base: G – Guanine) |
| aliphatic (hydrophobic) | the physico-chemical class — the same grouping the cell is coloured by, so the words and the colour can never disagree |
| Hydropathy (Kyte–Doolittle) | the residue's hydropathy index, +4.5 (isoleucine) to −4.5 (arginine) |
The two positions are the point of it. The column is a property of the alignment and moves if you realign; the residue number is the coordinate that maps back onto the real protein or gene, which is what you need when comparing against a structure, a mutation list or a paper. Working that out by counting gaps down a row is exactly the tedium this removes.
A gap says so and nothing more — no residue number, no name, no hydropathy. Nucleotides get
the base name and purine/pyrimidine but no hydropathy, because the scale is defined for
amino acids only; the same is true of the ambiguity codes B, X and Z, where the scale
simply has no value and inventing one would be a fabrication. The hydropathy scale is
Kyte & Doolittle (1982) — cited in full under Help → References.
Turn the display on or off and set the per-residue column width in Settings → Overlays (Sequence Alignment + Alignment column width; the width is remembered between sessions). Loading an alignment is undoable, and the whole track renders in every export (PDF, SVG, EPS, PNG). This first version is drawn in the rectangular root-on-left layout. There is a ready-made example in File → Demo Trees → Alignment next to Tree.
Under the alignment, a band shows how conserved each column is: a bar per column, with the column's consensus residue — its most common non-gap residue — drawn beneath it once the columns are wide enough to read one. It appears with the alignment; switch it off under Settings → Overlays → Conservation track.
It describes what you can see. The profile is scored over the tips currently
displayed, so entering a sub-tree or collapsing a clade re-scores it for the
sequences that are left. That is usually what you want when you are working
through a tree, and it does mean the numbers change as you navigate — so the band
labels itself with both the measure and the count, e.g. Consensus identity (n = 6), and that label goes into every export.
Two measures, chosen under Settings → Overlays → Conservation measure. Both run from 0 to 1, so the bar means the same thing either way, and both count gaps against a column — a column that is half gaps cannot score above 0.5.
- Consensus identity — the fraction of rows carrying the consensus residue. Reads directly as "how much of this column agrees", and is the easier of the two to state in a caption.
- Information content — the sequence-logo measure:
(log2(K) − H) / log2(K), where H is the Shannon entropy of the residues present and K is the alphabet size (4 for nucleotide, 20 for amino acid), scaled by the non-gap fraction. Use it when columns have no clear majority: it ranks a column split evenly between two residues above one split four ways, though identity scores them the same.
A few conventions worth knowing, because they change what a bar means:
- Upper and lower case are the same residue, as they are for the colouring.
- A row shorter than the alignment counts as gapped past its end.
- A gappy column still names its consensus residue — the bar already carries the gappiness. Ties go to the alphabetically first residue, so the same alignment always gives the same figure.
- Ambiguity codes (N, X, B, Z…) count as ordinary distinct residues, so a column full of them scores low rather than being quietly treated as conserved.
This is not the physico-chemical property score Jalview labels "Conservation" (Livingstone & Barton 1993), which is defined for amino acids only; the measures here work the same way on a nucleotide alignment. The full definitions and their citations are in Help → References.
One branch that is far longer than the rest — a distant outgroup, a fast-evolving
lineage — squashes the informative part of a phylogram to an unreadable sliver.
Turn on Settings → Layout → Break Long Branches and such a branch is drawn
shortened, with an axis-break glyph (─//─) across it — the tree analogue of a
broken axis in a chart — while the depth scale is re-derived from the capped
height so the rest of the tree reclaims the freed width. It is display-only:
the underlying branch length is never altered, and its true value is still shown as
the branch-length label.
A branch is treated as long when its length exceeds 8× the median of the tree's strictly-positive branch lengths — a robust threshold (unaffected by the one outlier being detected, or by the many zero-length branches of a polytomy-heavy tree), so a well-behaved, near-clock tree shows no breaks at all. This is a graphical convention (as offered by interactive viewers such as iTOL's cut long branches), not an inference step. It applies in all phylogram layouts — the unaligned and aligned phylogram views of the rectangular family (root-left / -top / -bottom and triangular), and the circular and unrooted radial views. In the aligned view the broken branch is capped and its tip still lines up at the common label column; in the radial views the outlier's spoke is shortened (the informative part fans out to reclaim the disc) with the break glyph rotated to ride the spoke. While it is on (rectangular), the small scale bar is kept — sized to the un-broken (ingroup) scale, so it reads correctly for the bulk of the tree — but the full-width scale axis and grid lines are hidden, since a single linear ruler across the whole width can't represent a truncated branch (the break mark denotes the discontinuity). Try it on the Break Long Branches demo tree.
A tanglegram compares two trees side by side with connectors linking their matching tips — the standard way to see how congruent two phylogenies are (a gene tree vs. a species tree, host vs. parasite, two reconstruction methods, …). With two or more trees open, choose Analysis → Create Tanglegram…, pick the two trees and the field to link their tips on (node name, taxonomy, or sequence), and the tanglegram opens in its own window (the second tree mirrored). It reports the number of crossing connectors and a size-normalised entanglement score (described below) — measures of how incongruent the two trees are.
To untangle it, click a clade's vertical bar to flip it (a topology-preserving rotation), or press Auto-untangle to have Archaeopteryx do it for both trees; both are undoable. The Colour selector recolours the connectors — uniform, Crossings (the crossing connectors highlighted in red), or by a tip attribute (taxonomy or an imported category, with a legend). Export… saves the figure as PDF, SVG, EPS, or PNG (the vector formats are publication-ready, document-white with the colouring preserved).
Auto-untangle heuristic. Auto-untangle reorders the two trees by rotating clades (reversing the child order at internal nodes — a topology-preserving operation) to reduce the number of crossing connectors between their matched tips. Archaeopteryx uses a barycentre heuristic — each clade's children are ordered by the mean vertical position of the tips they link to in the other tree — applied alternately to both trees and iterated to convergence, combined with random restarts, keeping the arrangement with the fewest crossings (it never increases the crossing count). Minimising the crossings of a tanglegram is NP-hard, so this is a heuristic. Foundational references:
- Barycentre crossing-reduction heuristic: Sugiyama K, Tagawa S, Toda M (1981): "Methods for visual understanding of hierarchical system structures", IEEE Transactions on Systems, Man, and Cybernetics 11(2):109–125.
- Tanglegram layout and crossing minimisation: Scornavacca C, Zickmann F, Huson DH (2011): "Tanglegrams for rooted phylogenetic trees and networks", Bioinformatics 27(13):i248–i256.
Entanglement (congruence score). Alongside the raw crossing count, the window reports a size-normalised entanglement in the range [0, 1]: 0 when the two leaf orderings agree perfectly (no crossings) and 1 when they are fully reversed. Two connectors cross exactly when their matched tips sit in the opposite vertical order in the two trees, so the total number of crossings is the number of discordant tip pairs — an inversion count, which is the Kendall rank-correlation (τ) distance between the two leaf orderings. Archaeopteryx divides that count by the maximum possible number of pairs, n(n−1)/2, so the score is comparable across trees of different sizes, and computes it in O(n log n) with a counting merge sort. This is a crossing-based (Kendall-τ) entanglement; it is a different, simpler definition from the leaf-position-based entanglement of the dendextend package. References:
- Rank-correlation (concordant/discordant pairs) basis: Kendall MG (1938): "A New Measure of Rank Correlation", Biometrika 30(1–2):81–93.
- Related, leaf-position-based entanglement: Galili T (2015): "dendextend: an R package for visualizing, adjusting and comparing trees of hierarchical clustering", Bioinformatics 31(22):3718–3720.
You can skip this section. Everything Archaeopteryx does, it does in the window — nothing here is needed to make a figure. This is for the narrower case where you would rather not be at the keyboard: rendering many trees at once, or regenerating a figure automatically whenever its data changes.
aptx_render draws a tree to a file without opening Archaeopteryx. It is the
same renderer and the same exporters the window uses, so a script produces
the figure you would have produced by hand.
- A folder of trees. One figure each, identical settings, no clicking.
- A figure that keeps changing. Re-run the same command after the alignment is rebuilt and the figure updates itself — no re-doing the display settings.
- A methods section that others can reproduce. The command is the record of how the figure was made, and it produces the same figure on anyone's machine.
If none of those describe you, the window is the better tool.
aptx_render lives in forester.jar — the same self-contained jar described
under Run from the jar; download it once and you have the
tool.
java -cp forester.jar org.forester.application.aptx_render tree.xml figure.pdf
That is a complete command: with no options at all it writes a 180 × 130 mm
figure at 300 dpi, drawn the way Archaeopteryx would draw that tree on opening
it. Run it with -help for the option list. A shell alias makes the rest of this
section easier to read:
alias aptx_render='java -cp /path/to/forester.jar org.forester.application.aptx_render'
| you write | you get |
|---|---|
figure.pdf |
vector PDF — the usual choice for a manuscript |
figure.svg |
vector SVG — for editing in Illustrator or Inkscape |
figure.eps |
vector EPS — where a journal still asks for it |
figure.png |
raster PNG, with the true DPI recorded in the file |
figure.jpg |
raster JPEG (lossy; PNG is better for line art) |
figure.tiff |
raster TIFF |
Vector text is drawn as outlines, so the file needs no fonts installed to look right anywhere. An extension it cannot write is refused outright rather than guessed at.
| option | what it does |
|---|---|
-size=<W>x<H><unit> |
figure size — 170x120mm, 8x6in, 1200x900px. Default 180x130mm |
-dpi=<n> |
dots per inch, default 300 |
-style=<s> |
rectangular (default), circular or unrooted |
-phylogram |
draw branch lengths to scale |
-cladogram |
ignore branch lengths |
-support |
show confidence / support values |
-bl |
show branch-length values |
-color=<ref> |
colour tips by a property, e.g. data:host |
-help |
the option list |
With neither -phylogram nor -cladogram, the tree is drawn as a phylogram when
it has branch lengths and a cladogram when it does not — the same choice
Archaeopteryx makes on opening it.
-color takes a phyloXML property reference. Give it one the tree does not have
and it stops and tells you which ones it does have, rather than quietly writing
an uncoloured figure.
Size is the one option that repays a little thought, because the figure is laid out at its physical size, not at its pixel count. Text is set in points, so a 12-point label occupies the same fraction of a 170 mm page whether you render it at 150 or 600 dpi. That has one consequence worth knowing:
Prefer a physical size (
mmorin).-size=1000x1000px -dpi=300is a page only 3.3 inches across, on which the default font is enormous: labels collide and, in circular layouts, get truncated — with the page apparently half empty. The same tree at-size=250x250mmrenders cleanly.
So:
mm/inset the page;-dpithen decides how many pixels a raster export puts on it. Vector output ignores-dpientirely.pxsets the pixel count;-dpithen decides how large the page is physically. Useful for a figure destined for a screen, but easy to make accidentally tiny.
Journal column widths are a good starting point: -size=85x110mm for a single
column, -size=170x120mm for a double.
If the tree is too dense for the size you asked for, Archaeopteryx hides labels
rather than overlapping them — and aptx_render tells you it did, so a figure
never loses labels silently:
Warning: some labels were hidden by "Auto-hide Labels" to avoid overlap at this size.
A larger -size is the fix.
# a double-column PDF with support values
aptx_render -size=170x120mm -support tree.xml figure.pdf
# a circular figure, coloured by a metadata property, as editable SVG
aptx_render -style=circular -size=250x250mm -color=data:host tree.xml figure.svg
# a single-column PNG at 600 dpi
aptx_render -size=85x110mm -dpi=600 tree.xml figure.png
# every tree in a folder
for t in trees/*.xml; do
aptx_render -size=170x120mm "$t" "figures/$(basename "${t%.xml}").pdf"
done
The render starts from documented defaults plus the options you passed. It does not pick up whatever you last set in the Archaeopteryx window — if it did, the same command would produce different figures on different machines, which would defeat the purpose. Your saved settings are neither read nor changed by it.
Archaeopteryx's display settings live in its control panel, so drawing a tree means building that panel; the window is created off-screen and never shown. On a desktop machine this simply works. On a headless server — a cluster node, a CI runner — run it under a virtual display:
xvfb-run -a java -cp forester.jar org.forester.application.aptx_render \
tree.xml figure.pdf
(xvfb-run comes from the xvfb package on Debian / Ubuntu.)
This is a first version, deliberately small, to find out whether people want it. It renders a tree from the options above; it does not yet reproduce a figure you composed in the window — annotation columns, clade bands, time axes, tip images and the rest are not reachable from the command line. Making them so means letting Archaeopteryx save a figure's full appearance into the tree file, which is a larger piece of work worth doing only if there is appetite for it.
If this is useful to you, or nearly useful, say so on the issue tracker — including which setting you most want to reach from a script.
An installed Archaeopteryx has no console. The Windows launcher is a windowed
one, a macOS .app hands its output to the system, and a Linux desktop entry
sends it to the session journal — so if something failed, the details used to go
nowhere you could reach, and the most you could report was "it stopped drawing".
Archaeopteryx now writes unexpected errors to a log file:
~/.archaeopteryx/archaeopteryx.log
Open it from Help → Show Error Log. If something has gone wrong in the current session, a quiet ⚠ error logged marker also appears in the menu bar — click it to open the log, or dismiss it. There is deliberately no pop-up: a failure inside the drawing code repeats on every redraw, and a dialog for each one would make the program unusable.
If you hit a bug, attach that file to your report. It holds the stack trace, which is the part that makes a problem findable. Two details keep it useful rather than enormous: a failure that repeats is written once and then counted ("… the same failure repeated 412 more times"), and the file restarts itself if it ever grows past a couple of megabytes, so a runaway error cannot fill your disk.
This is the home of Archaeopteryx: the website (docs/, served by GitHub
Pages), this documentation, the citation metadata, and the release stream.
The source code lives in the forester
project — an open-source Java library and command-line toolkit for phylogenetics,
of which Archaeopteryx is the interactive front end. The release workflow here
builds the installers from a pinned forester tag and publishes them to this
repository's Releases, so Archaeopteryx has its own versioned, citable identity.
The online version, Archaeopteryx.js,
is a separate JavaScript implementation with its own repository,
archaeopteryx-js. The two are kept in
step on the things a shared tree depends on (formats, "Color by", node data).
A dedicated publication is in preparation. Until then, use the Cite this
repository button (backed by CITATION.cff); once a release is
archived on Zenodo, its DOI provides a stable, versioned citation.
GPL-3.0 — free and open source. © Christian M. Zmasek.