Phylogenetic tree

Evolutionary biology phylogenetic trees — showing evolutionary relationships and divergence distances between species, genes, or sequences.

References:

• Felsenstein, J. (2004). Inferring Phylogenies. Sinauer Associates.
• Baum, D.A. & Smith, S.D. (2013). Tree Thinking: An Introduction to Phylogenetic Biology. Roberts & Company.
• Letunic, I. & Bork, P. (2024). iTOL v6: Interactive Tree Of Life. Nucleic Acids Res, 52(W1), W78-W82.
• Huson, D.H. et al. (2007). Dendroscope: An interactive viewer for large phylogenetic trees. BMC Bioinformatics, 8, 460.
• Cardona, G. et al. (2008). Extended Newick: it is time for a standard representation of phylogenetic networks. BMC Bioinformatics, 9, 532.
• Newick format specification: https://phylipweb.github.io/phylip/newicktree.html
• Xu, S. et al. (2022). ggtree: Data Integration, Manipulation and Visualization of Phylogenetic Trees. R package.

1. Key Differences from Other Schematex Diagram Types

Key distinction: The phylogenetic tree is the only Schematex diagram type where branch length carries quantitative information — it is a phylogram, not a cladogram (unless the user explicitly selects cladogram mode).

2. Tree Components & Terminology

2.1 Node Types

2.2 Branch (Edge) Properties

2.3 Tree Semantics

3. Tree Representation Modes

Schematex supports 3 tree representation modes that determine the visual meaning of branch length:

3.1 Phylogram (Default)

• Branch length proportional to evolutionary distance (substitutions/site)
• SVG horizontal length of each branch = branchLength × scale
• Tips do not necessarily align (because evolutionary rates differ)
• A scale bar is required at the bottom (e.g. "0.05 substitutions/site")
• This is the most information-dense mode and is the default

3.2 Cladogram

• Branch length has no meaning — only shows topology (who is closer to whom)
• All tips align to the same vertical line
• Internal nodes distributed at equal intervals
• Suitable when only branching order matters
• Activated with [mode: cladogram]

3.3 Chronogram (Time Tree)

• Branch length proportional to divergence time (units: Mya or years)
• All tips align to "present" (right side)
• X axis is a time axis (left = past → right = present)
• Geological time scale or numeric time axis shown at the bottom
• Activated with [mode: chronogram]
• Requires branch lengths in Newick + [mrsd: "2026"] (most recent sampling date)

4. Layout Types

4.1 Rectangular Layout (Default)

The most standard layout: branches follow an L-shaped path (horizontal first, then a vertical turn).

Root ─┬── Taxon_A
      │
      └─┬── Taxon_B
        │
        └─┬── Taxon_C
          │
          └── Taxon_D

• Root on left, tips on right
• Horizontal branch = evolutionary distance
• Vertical line = connector only (no length meaning)
• Best suited for small to medium trees with ≤100 tips

SVG implementation:

• Horizontal branches: <line x1 y1 x2 y2> or <path d="M x1,y1 H x2">
• Vertical connector lines: <line> from topmost to bottommost child node
• Branches as step path: M x1,y H x2 V y2 (horizontal for branch length, then vertical to child)

4.2 Slanted (Diagonal) Layout

Same topology as rectangular, but diagonal lines replace L-shapes:

Root ──── Taxon_A
    \
     ──── Taxon_B
      \
       ─── Taxon_C
        \
         ── Taxon_D

• Branches are straight lines (diagonal from parent to child)
• <line> or <path d="M x1,y1 L x2,y2">
• Visually more compact
• Activated with [layout: slanted]

4.3 Circular (Fan) Layout

Root at center, tips distributed around the circumference:

• Angle allocation: each tip occupies 360° / numTips
• Internal nodes positioned at the angular midpoint of their children
• Branches extend radially
• Ideal for large trees (50-500+ tips) — most efficient use of space
• Activated with [layout: circular]

SVG implementation:

• Radial branches: <path> with M + arc segments
• Vertical connector lines → arcs: <path d="M ... A ...">
• Tip labels rotated tangentially: transform="rotate(angle)"

Parameters:

• openAngle: fan opening angle (default 0 = full 360°; set to e.g. 30 to leave a gap for legend)

4.4 Unrooted (Radial Equal-Angle) Layout

Unrooted tree — emphasizes distance relationships rather than ancestral direction:

• Equal-angle algorithm: angle allocated to each subtree ∝ number of tips in that subtree
• An arbitrary internal node is chosen as the drawing center, radiating outward
• Suitable for showing network-like evolutionary distance relationships without implying direction
• Activated with [layout: unrooted]

Daylight improvement (optional optimization):

• Iterative adjustment on top of equal-angle: visit each internal node and rotate subtrees so the "daylight" (gap angle between adjacent subtrees) is equalized
• Reduces tip clustering

5. Visual Encoding Conventions

5.1 Branch Styling

5.2 Node Decoration

5.3 Bootstrap / Support Value Display

Bootstrap values are key visual elements in phylogenetic trees and have two display modes:

Mode A: Numbers on branches (default)

• Numbers annotated next to internal nodes (slightly above branch midpoint)
• Font: 9px, class="schematex-support-label"
• Only values ≥50 are displayed (<50 are generally unreliable and omitted)
• Color coding (optional): ≥95 green, 75-94 yellow, 50-74 orange

Mode B: Colored dots on nodes

• Internal nodes shown as dots, color = support strength
• Gradient scale: red (low) → yellow (medium) → green (high)
• Circle size can be fixed or proportional to support value

Support value thresholds (standard conventions):

5.4 Tip Labels

Label rotation in circular layout:

• Right semicircle (0-180°): normal orientation, label faces outward
• Left semicircle (180-360°): label rotated 180° to maintain readability
• text-anchor: "start" for right semicircle, "end" for left semicircle

5.5 Scale Bar

Phylogram and chronogram must have a scale bar:

• Position: bottom-left
• Phylogram: shows substitution distance (e.g. ── 0.05)
• Chronogram: shows time (e.g. ── 10 Mya)
• SVG: <line> + <text>, class="schematex-scale-bar"
• Length: automatically calculated as a round number (0.01, 0.05, 0.1, 0.5, 1.0...) occupying ~15-25% of tree width

5.6 Clade Highlighting

Clade highlighting is a core visual feature of phylogenetic trees — marking monophyletic groups with colored blocks:

Mode A: Background shading

• Semi-transparent rectangle (rectangular) or sector (circular) covering the entire clade
• <rect> with fill-opacity: 0.15 or <path> (arc sector)
• Clade label on the right (bold, 12px)

Mode B: Branch coloring

• All branches within the clade colored with the same color
• Inherited by tip labels
• The most minimal visual approach

DSL:

clade Mammals = (Human, Mouse, Dog) [color: "#1E88E5", label: "Mammals"]
clade Birds = (Chicken, Eagle) [color: "#43A047", label: "Aves"]

6. Newick Format Support

Schematex's phylogenetic parser must natively support the Newick format — it is the universal language of evolutionary biology.

6.1 Newick Grammar (Standard)

tree       = subtree ";" 
subtree    = leaf | internal
leaf       = name
internal   = "(" branchset ")" name
branchset  = branch ("," branch)*
branch     = subtree length
name       = EMPTY | UNQUOTED_STRING | QUOTED_STRING
length     = EMPTY | ":" NUMBER

UNQUOTED_STRING = /[^\s():,;\[\]']+/
QUOTED_STRING   = "'" /([^']|'')*/ "'"
NUMBER          = /[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?/

6.2 Newick Examples (All must pass the parser)

# Minimal topology — no names, no lengths
(,,(,));

# Leaf names only
(A,B,(C,D));

# All nodes named
(A,B,(C,D)E)F;

# With branch lengths (most common format)
(A:0.1,B:0.2,(C:0.3,D:0.4):0.5);

# Internal node with name + length
(A:0.1,B:0.2,(C:0.3,D:0.4)E:0.5)F;

# Lengths only, no names
(:0.1,:0.2,(:0.3,:0.4):0.5);

# Multifurcating tree (polytomy)
(A,B,C,D);

# Single leaf (degenerate)
(A);

# Quoted label (with special characters)
('Homo sapiens':0.1,'Mus musculus':0.2);

6.3 Extended Newick (NHX) — Optional Support

(A:0.1[&&NHX:B=100],B:0.2[&&NHX:B=85],(C:0.3,D:0.4)E:0.5[&&NHX:B=72])F;

• [&&NHX:key=value:...] appended after node name
• B = bootstrap, T = taxonomy, S = species name
• P1 support: parsing the B (bootstrap) field is sufficient

6.4 Schematex DSL (Extended Syntax)

Newick is concise but not easy to read. Schematex provides an extended DSL for adding visual configuration:

phylo "Tree of Life"
  newick: "(((Human:0.1,Chimp:0.08):0.03,Gorilla:0.12):0.15,Dog:0.35,(Cat:0.30,Mouse:0.45):0.2);"
  
  # Or use Schematex native DSL (small trees)
  # See Section 8

  clade Primates = (Human, Chimp, Gorilla) [color: "#1E88E5"]
  clade Carnivora = (Dog, Cat) [color: "#E53935"]
  
  style [layout: rectangular, mode: phylogram]
  scale [label: "substitutions/site"]

7. Schematex Native DSL (Alternative to Newick)

For small trees or hand-written scenarios, Schematex provides an indent-based DSL as a readable alternative to Newick:

phylo "Vertebrate Evolution" [layout: rectangular, mode: phylogram]

# Indentation = nesting (parent-child), colon followed by = branch length
root:
  :0.15
    :0.03
      Human: 0.1
      Chimp: 0.08
    Gorilla: 0.12
  Dog: 0.35
  :0.2
    Cat: 0.30
    Mouse: 0.45

scale "substitutions/site"
clade Primates = (Human, Chimp, Gorilla) [color: "#1E88E5"]

Indent DSL rules:

• Each indentation level = one level of nesting in the tree (equivalent to Newick parentheses)
• Name: length = leaf node with branch length
• :length = unnamed internal node with branch length
• Name: (no length) = leaf node, cladogram mode
• Comments # are ignored

8. DSL Grammar (Complete EBNF)

document       = header config* tree_def annotation* 
header         = "phylo" quoted_string? header_props? NEWLINE
header_props   = "[" header_prop ("," header_prop)* "]"
header_prop    = layout_prop | mode_prop | root_prop | misc_prop

layout_prop    = "layout:" LAYOUT_TYPE
LAYOUT_TYPE    = "rectangular" | "slanted" | "circular" | "unrooted"

mode_prop      = "mode:" TREE_MODE
TREE_MODE      = "phylogram" | "cladogram" | "chronogram"

root_prop      = "unrooted"
misc_prop      = "branch-width:" NUMBER
               | "openAngle:" NUMBER
               | "mrsd:" quoted_string

config         = scale_def | outgroup_def
scale_def      = "scale" quoted_string? NEWLINE
outgroup_def   = "outgroup:" IDENTIFIER NEWLINE

tree_def       = newick_def | indent_def
newick_def     = "newick:" NEWICK_STRING NEWLINE
indent_def     = "root:" NEWLINE (INDENT tree_node+ DEDENT)

tree_node      = (IDENTIFIER | EMPTY) ":" NUMBER? support? NEWLINE
               (INDENT tree_node+ DEDENT)?
support        = "[" NUMBER "]"  # bootstrap or posterior probability value

annotation     = clade_def | label_def | comment
clade_def      = "clade" IDENTIFIER "=" "(" id_list ")" clade_props? NEWLINE
id_list        = IDENTIFIER ("," IDENTIFIER)*
clade_props    = "[" clade_prop ("," clade_prop)* "]"
clade_prop     = "color:" quoted_string | "label:" quoted_string
               | "highlight:" HIGHLIGHT_MODE
HIGHLIGHT_MODE = "branch" | "background" | "both"

label_def      = "label" IDENTIFIER "=" quoted_string label_props? NEWLINE
label_props    = "[" kv_prop ("," kv_prop)* "]"

comment        = "#" [^\n]* NEWLINE

IDENTIFIER     = /[a-zA-Z_][a-zA-Z0-9_.-]*/
NUMBER         = /[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?/
quoted_string  = '"' /[^"]*/ '"'
NEWICK_STRING  = /[^;]+;/
INDENT         = increase in leading whitespace  # deeper indentation
DEDENT         = decrease in leading whitespace  # shallower indentation
NEWLINE        = /\n/

9. Rendering Details

9.1 Color Palette (Default Clade Colors)

When the user does not specify a color, colors are automatically assigned in declaration order from the palette:

9.2 SVG Structure

<svg class="schematex-phylo" viewBox="0 0 {W} {H}">
  <defs>
    <!-- clip paths, markers if needed -->
  </defs>
  
  <g class="schematex-branches" transform="translate({padL},{padT})">
    <!-- All branch paths: <path> or <line> elements -->
    <path class="schematex-branch" d="M ..." stroke="#333" />
    <!-- Clade-colored branches override stroke -->
    <path class="schematex-branch schematex-clade-Primates" d="..." stroke="#1E88E5" />
  </g>
  
  <g class="schematex-clade-highlights">
    <!-- Background shading rectangles/arcs -->
    <rect class="schematex-clade-bg" ... fill="#1E88E5" fill-opacity="0.12" />
  </g>
  
  <g class="schematex-nodes">
    <!-- Internal node support dots -->
    <circle class="schematex-support-dot" cx="..." cy="..." r="4" fill="#43A047" />
    <!-- Tip dots (if enabled) -->
  </g>
  
  <g class="schematex-labels">
    <!-- Tip labels -->
    <text class="schematex-tip-label" x="..." y="..." font-style="italic">Homo sapiens</text>
    <!-- Support value text (if mode A) -->
    <text class="schematex-support-label" x="..." y="...">98</text>
  </g>
  
  <g class="schematex-scale-bar" transform="translate({x},{y})">
    <line x1="0" y1="0" x2="{len}" y2="0" stroke="#333" stroke-width="1.5" />
    <line x1="0" y1="-4" x2="0" y2="4" stroke="#333" stroke-width="1" />
    <line x1="{len}" y1="-4" x2="{len}" y2="4" stroke="#333" stroke-width="1" />
    <text x="{len/2}" y="16" text-anchor="middle">0.05</text>
  </g>
  
  <g class="schematex-legend">
    <!-- Clade legend entries -->
  </g>
</svg>

9.3 CSS Classes

10. Layout Algorithm Details

10.1 Rectangular Phylogram Layout

Input: Rooted tree with branch lengths Output: (x, y) for each node

Step 1 — Leaf Y-coordinates:

leaves = collectLeaves(root)  // in-order traversal
for i, leaf in leaves:
    leaf.y = i * tipSpacing    // tipSpacing default = 20px

Step 2 — Internal node Y-coordinates:

function assignY(node):
    if node.isLeaf: return node.y
    children_ys = [assignY(child) for child in node.children]
    node.y = mean(children_ys)   // center between first and last child

Step 3 — X-coordinates (distance from root):

root.x = 0
function assignX(node):
    for child in node.children:
        child.x = node.x + child.branchLength * scale  // scale based on available width
        assignX(child)

Step 4 — Scale factor:

maxRootToTip = max distance from root to any tip
scale = availableWidth / maxRootToTip  // fit tree to canvas width

10.2 Circular Layout

Step 1 — Angle allocation:

totalAngle = 360 - openAngle  // openAngle default = 0 (full circle)
leaves = collectLeaves(root)
for i, leaf in leaves:
    leaf.angle = (i / numLeaves) * totalAngle + startAngle

Step 2 — Internal node angles:

node.angle = mean of children angles  // midpoint between leftmost and rightmost child

Step 3 — Radial distance (from center):

node.radius = node.distanceFromRoot * scale
// Convert to Cartesian:
node.x = centerX + node.radius * cos(node.angle)
node.y = centerY + node.radius * sin(node.angle)

Step 4 — Arc paths for connectors:

// Parent connects to children via:
// 1. Arc from min(child.angle) to max(child.angle) at parent.radius
// 2. Radial line from parent.radius to child.radius at child.angle

10.3 Unrooted (Equal-Angle) Layout

function layoutUnrooted(node, startAngle, arcAngle, parentX, parentY):
    node.x = parentX + node.branchLength * scale * cos(startAngle + arcAngle/2)
    node.y = parentY + node.branchLength * scale * sin(startAngle + arcAngle/2)
    
    if node.isInternal:
        totalTips = sum(child.numTips for child in node.children)
        currentAngle = startAngle
        for child in node.children:
            childArc = arcAngle * (child.numTips / totalTips)  // proportional arc per subtree
            layoutUnrooted(child, currentAngle, childArc, node.x, node.y)
            currentAngle += childArc

10.4 Cladogram Mode Adjustment

When mode: cladogram:

• All branch lengths are ignored
• Tips aligned to right edge: leaf.x = maxX
• Internal nodes distributed at equal intervals: node.x = maxX - (node.depth * stepWidth)

11. Design Principles for Beautiful Phylogenetic Trees

11.1 Spacing & Proportions

• Tip spacing: 18-24px (rectangular), 12-16px (circular for large trees)
• Aspect ratio: Width ≥ Height × 1.5 for rectangular (leaves room for tip labels)
• Label gap: 6px between tip point and label start
• Margin: left 20px (scale bar), right auto (longest label + 20px), top/bottom 20px

11.2 Typography

• Tip labels: upright 12px for common names, italic 12px for species binomials
• Support values: 9px, fill: #666
• Scale bar label: 10px, text-anchor: middle
• Clade labels: 13px bold, color = clade color

11.3 Color Strategy

• Branches: default #333 — dark enough but not harsh
• Clades: use the 8-color palette from Section 9.1 — moderate saturation, accessible (passes WCAG AA)
• Support dots: Green → Yellow → Orange → Red gradient, intuitive (green = good)
• Background highlight: same clade color but opacity: 0.10-0.15 — does not interfere with branch readability
• Never use >8 clade colors — too many colors is noise, not information

11.4 Readability Rules

1. Branch lines always above labels (z-order: branches → highlights → labels)
2. Avoid label overlap: if tips are too dense, truncate or increase tipSpacing
3. Circular layout label flipping: left semicircle labels must be rotated 180° for readability
4. Scale bar should be neither too long nor too short: target 15-25% of tree width
5. Support values only shown ≥50: values below 50 are noise

12. Test Cases

Case 1: Basic Phylogram (Newick Input)

phylo "Simple Vertebrates"
  newick: "((Human:0.1,Mouse:0.3):0.05,(Chicken:0.4,(Zebrafish:0.6,Frog:0.5):0.15):0.1);"
  scale "substitutions/site"

Verify: branch lengths are proportional, Mouse's branch is 3× longer than Human's, scale bar at the bottom.

Case 2: Cladogram with Clades

phylo "Animal Kingdom" [mode: cladogram]
  newick: "(((Cat,Dog)Carnivora,(Human,Chimp)Primates)Mammalia,(Chicken,Eagle)Aves);"
  clade Mammals = (Cat, Dog, Human, Chimp) [color: "#1E88E5", label: "Mammalia"]
  clade Birds = (Chicken, Eagle) [color: "#43A047", label: "Aves"]

Verify: all tips right-aligned (cladogram), Mammalia and Aves highlighted in different colors.

Case 3: Bootstrap Support Values

phylo "Primate Phylogeny"
  newick: "((Human:0.02,Chimp:0.03):0.01[&&NHX:B=100],(Gorilla:0.05,(Orangutan:0.08,Gibbon:0.10):0.04[&&NHX:B=72]):0.03[&&NHX:B=95]);"
  scale "substitutions/site"

Verify: the node near root shows 95 (green dot), Human-Chimp node shows 100 (green), Orangutan-Gibbon node shows 72 (orange).

Case 4: Circular Layout (Large Tree)

phylo "Bacterial Diversity" [layout: circular]
  newick: "((((Ecoli:0.1,Salmonella:0.12):0.05,Vibrio:0.2):0.08,((Bacillus:0.15,Staph:0.18):0.06,Listeria:0.22):0.1):0.15,((Myco_tb:0.3,Myco_leprae:0.28):0.12,(Strepto:0.25,Lactobacillus:0.2):0.08):0.2);"
  
  clade Gamma = (Ecoli, Salmonella, Vibrio) [color: "#1E88E5", label: "γ-Proteobacteria"]
  clade Firmi = (Bacillus, Staph, Listeria, Strepto, Lactobacillus) [color: "#E53935", label: "Firmicutes"]
  clade Actino = (Myco_tb, Myco_leprae) [color: "#43A047", label: "Actinobacteria"]
  
  scale "substitutions/site"

Verify: circular layout, 3 clades in different colors, labels on the outside and readable (left semicircle flipped), radial scale bar present.

Case 5: Unrooted Tree

phylo "Gene Family" [layout: unrooted]
  newick: "(A:0.3,B:0.4,(C:0.35,D:0.2):0.15,(E:0.5,F:0.45):0.25);"

Verify: no root marker, all branches radiate from the center, angles evenly divided by number of tips.

Case 6: Chronogram (Time-Scaled)

phylo "Mammal Divergence" [mode: chronogram, mrsd: "0"]
  newick: "((Human:6.4,Chimp:6.4):1.1,((Dog:52,Cat:52):12,(Mouse:75,Rat:75):10):5);"
  scale "Million years ago (Mya)"

Verify: all tips aligned to the right (present = 0 Mya), X axis left to right = past to present, Human-Chimp divergence point at ~6.4 Mya, Mouse-Rat at ~75 Mya. Time axis at the bottom.

Case 7: Schematex Native DSL (Indent-Based)

phylo "Simple Tree"

root:
  :0.15
    :0.03
      Human: 0.1
      Chimp: 0.08
    Gorilla: 0.12
  Dog: 0.35

clade Apes = (Human, Chimp, Gorilla) [color: "#1E88E5"]
scale "substitutions/site"

Verify: equivalent to Newick ((Human:0.1,Chimp:0.08):0.03,Gorilla:0.12):0.15,Dog:0.35);, DSL format is more readable.

Case 8: Polytomy (Multi-furcation)

phylo "Rapid Radiation"
  newick: "((A:0.1,B:0.1,C:0.1,D:0.1):0.5,E:0.6);"

Verify: internal node has 4 child nodes (not 2), representing a "hard polytomy" or unresolved topology.

Case 9: Species Names with Special Characters

phylo "Hominids"
  newick: "('Homo sapiens':0.02,'Pan troglodytes':0.03,'Gorilla gorilla':0.05,'Pongo pygmaeus':0.08);"

Verify: quoted labels correctly parsed, species names displayed in italic (Homo sapiens).

13. Implementation Priority