Tree Formatting

Step 0b: Validate Newick Tree File

Before rendering, validate the tree file. Tree-formatting scripts should include a validation step early on.

What to check

• File exists and is non-empty
• Valid Newick syntax — parseable by ape::read.tree() (R) or ete3.Tree() (Python)
• Tip count — report number; flag if unexpectedly low (< 3) or very high (> 5000)
• Rooted vs unrooted — report rooting status (ape::is.rooted())
• Zero-length branches — warn if present (can cause rendering issues with phylograms)
• Polytomies — report if multifurcations exist (ape::is.binary())
• Tip label format — check for | characters (breaks iTOL), spaces, unusual characters

R validation chunk (ggtree scripts)

#| label: validate-tree

library(ape)

tree_path <- here("data/phylogenetics/tree.treefile")
stopifnot("Tree file not found" = file.exists(tree_path))

tree <- read.tree(tree_path)
cat("Tips:", Ntip(tree), "\n")
cat("Rooted:", is.rooted(tree), "\n")
cat("Binary:", is.binary(tree), "\n")

# Zero-length branches
if (!is.null(tree$edge.length)) {
  n_zero <- sum(tree$edge.length == 0)
  if (n_zero > 0) cat("WARNING:", n_zero, "zero-length branches\n")
}

# Tip label issues (pipe breaks iTOL)
has_pipe <- grepl("\\|", tree$tip.label)
if (any(has_pipe)) {
  cat("WARNING:", sum(has_pipe), "tips contain '|' — will break iTOL annotations\n")
}

Python validation chunk (iTOL upload scripts)

#| label: validate-tree

from ete3 import Tree

tree_path = PROJECT_ROOT / "data/phylogenetics/tree.treefile"
assert tree_path.exists(), f"Tree file not found: {tree_path}"

tree = Tree(str(tree_path))
tips = tree.get_leaf_names()
print(f"Tips: {len(tips)}")

# Check for pipe characters
pipe_tips = [t for t in tips if "|" in t]
if pipe_tips:
    print(f"WARNING: {len(pipe_tips)} tips contain '|' — must relabel before iTOL")

Step 1: Choose the Tree Type

Help the user select the right visualization. Ask about purpose and tree size, then recommend from the options below.

Tree type options

Decision flow

1. How many tips?
   • < 250: Simple rectangular (all tips labeled)
   • 250+: Collapsed rectangular or circular — ask user preference
2. Branch lengths meaningful?
   • Yes -> phylogram option available
   • No / topology-only -> cladogram
3. Layout: Rectangular or circular? Often useful to produce both.
4. Both phylogram and cladogram? Often useful to produce both for rectangular trees.
5. Which species to highlight? -> Focal species list (see Step 2)

Step 2: User Prompts (Ask Before Building)

Gather these decisions before writing any code:

1. Rendering backend: ggtree or iTOL? (see Step 0)
2. Tree type: Offer the relevant options from the table above based on tip count
3. Collapsing strategy: "Should pure clades be collapsed? (Recommended for trees with >100 tips.)"
   • Which groups to collapse? The collapse_groups parameter controls which taxonomic groups are eligible. Common choices:
     • c("Bilateria") — only collapse bilaterians (keeps sponges/cnidarians expanded)
     • c("Bilateria", "Protostomia", "Deuterostomia") — collapse specific groups
     • NULL — all groups eligible for collapsing
   • Purity threshold: 100% pure (strict) or 90%+ (relaxed)?
   • Model species on triangles: Collapsed triangles automatically list gene names of model species (human, mouse, fly, worm) inside them, e.g., "Bilateria (36 tips: LAMA1, LAMA2, LAMB1)". This ensures key gene family members remain visible even when the clade is collapsed.
   • Never collapse by gene family — unless eggNOG orthogroup data is available
4. Labeling level: "What level of tip labeling do you want?"
   • No labels — branch colors only (good for overview figures)
   • All tips labeled — every visible tip gets a label (good for small trees)
   • Selective — model species + focal species only (recommended for large trees)
5. Focal species list (if selective labeling): "Which non-model species should be individually labeled? Typically sponges + species with single-cell data (e.g., Hydra, Nematostella). Provide full species names."
6. Rooting strategy: "Midpoint root, or specify an outgroup?"
7. Gene name resolution: "Do tips include model species from non-Swiss-Prot sources (e.g., tr| entries, Ensembl, FlyBase, WormBase)? If so, we need to look up gene symbols." -> See gene-lookup skill for database-specific workflows.
8. iTOL project (if iTOL backend): "Which iTOL project should the tree go in? Name an existing project, or create a new one in the iTOL web UI (My Trees > New Project) and tell me the name." Set as ITOL_PROJECT env var or hardcode in the upload script.

Step 3a: Build with ggtree

All ggtree templates are Quarto .qmd documents following the project's data science conventions (YAML frontmatter with status field, git hash, BUILD_INFO.txt).

Collapsed rectangular (phylogram / cladogram)

Reference template: ~/.claude/skills/tree-formatting/templates/ggtree/collapsed_rectangular.qmd

This template is a complete, runnable .qmd with all tuned style parameters. Copy it into the project's scripts/ directory and adapt the sections marked PROJECT-SPECIFIC:

• File paths
• Tip label parsing functions (must match actual label formats in the tree)
• Taxonomy mapping (species -> group)
• Model and focal species lists
• collapse_groups parameter (which taxonomic groups to collapse)

The template handles: tree loading, midpoint rooting, pure-clade collapsing by taxonomic group, branch coloring by taxonomy, all visible tips labeled, model species gene names on collapsed triangle labels, formula-based page sizing, and PDF output.

Key features:

• No branch capping — branch lengths are never manipulated (this is a hard rule)
• Formula-based page sizing — INCHES_PER_TIP = 0.12, height = max(8, n_visible * INCHES_PER_TIP)
• collapse_groups parameter — controls which taxonomic groups are eligible for collapsing (e.g., c("Bilateria") to only collapse bilaterians, or NULL for all)
• Model species gene names on triangles — collapsed labels show "Group (N tips: GENE1, GENE2, ...)" so key gene family members remain visible
• Collapse label positioning — labels at max(pre_data$x[tip_ids]) (triangle tip), not at internal node x (triangle base)

Collapsed circular (overview and/or labeled)

Reference template: ~/.claude/skills/tree-formatting/templates/ggtree/collapsed_circular.qmd

Same structure as rectangular — adapt PROJECT-SPECIFIC sections. Produces:

• Circular overview (no labels): 20" square page, branch colors only
• Circular labeled (selective labels): 28" square page, manually positioned labels

Critical circular gotcha: Labels must be positioned BEFORE collapse() is called. The template handles this by computing angles from y-position (y / max_y * 360), flipping text on the left half of the circle, and using geom_text() with explicit angle/hjust values instead of geom_tiplab2().

Other tree types

For simple rectangular or unrooted trees, no template exists yet. Build from ggtree