Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tree Visualization

necom nwk can render Newick trees as publication-quality LaTeX (via the Forest package) or as self-contained SVG images. Both outputs share the same style system, so NHX annotations produce consistent visual results whether you compile a .tex document or open an .svg file in a browser.

  • to-tex generates a complete .tex document by merging Forest code with a built-in template, ready for compilation with xelatex or tectonic.
  • to-svg generates a self-contained SVG image with embedded CSS.

Example files used below are in docs/data/.

Core Commands

necom nwk to-tex

Generates a complete LaTeX document.

necom nwk to-tex docs/data/catarrhini.nwk -o catarrhini.tex

Compile the output:

tectonic catarrhini.tex
# or
latexmk -xelatex catarrhini.tex

Use --forest to pass through an existing Forest code file instead of a Newick tree:

necom nwk to-tex forest.tex --forest -o document.tex

necom nwk to-svg

Generates a self-contained SVG image.

necom nwk to-svg docs/data/catarrhini.nwk -o catarrhini.svg

By default to-svg auto-detects phylogram mode when branch lengths are present. Use -w and -v to adjust the canvas width and vertical leaf spacing:

necom nwk to-svg docs/data/catarrhini.nwk -w 1200 -v 30 -o catarrhini.svg

Style System

Styles are attached to nodes as NHX annotations. The same properties are interpreted consistently by to-tex and to-svg.

dot

Draws a filled circle at the node.

[&&NHX:dot=red]

When no color is given, dot is automatically applied to named internal nodes.

bar

Draws a short perpendicular bar on the edge between the node and its parent. Useful for marking events or character-state changes.

[&&NHX:bar=blue]

rec

Draws a background rectangle behind the entire clade rooted at the node.

[&&NHX:rec=LemonChiffon]

This is often combined with the soft palette defined in the LaTeX template.

tri

Draws a triangle to the right of the node, commonly used for collapsed clades or to emphasize a leaf.

[&&NHX:tri=green]

color, label, and comment

  • color sets the text color of the node name and labels.
  • label adds an explicit label beside the node.
  • comment adds a small note below a leaf label (joined with T, S, rank, and member if present).
[&&NHX:color=red:label=important:comment=note]

Colors and Global Settings

The built-in LaTeX template provides a soft, muted palette (for example ChampagnePink, TeaRose, and Celadon). SVG output uses the same default colors:

  • Branch lines are gray (rgb(129,130,132), 1 pt).
  • Node dots are small black circles (class="dot", default fill rgb(26,25,25), 2.5 px radius).
  • A sans-serif font is used.

LaTeX-specific font behavior:

  • By default, the template uses Noto Sans, which is widely available.
  • Use --no-default-style to keep the template’s original Fira Sans / Source Han Sans SC setup instead of injecting the default Noto Sans configuration.

SVG Notes

  • SVG output escapes XML special characters (& < > " ') in attribute values and text content.
  • Underscores (_) in names and annotation values are replaced with spaces, matching the LaTeX output.
  • Visual layers are drawn in this order: subtree rectangles (rec), triangles (tri), branch lines, bars (bar), dots (dot), and finally text labels/comments.

Advanced Features

Phylogram Mode (--bl)

When the input tree contains branch lengths, --bl produces a phylogram with an automatically computed scale bar. The scale values (e.g., 0.01, 0.05, 1.0) are chosen based on the tree height and rendered in the lower-right corner in both LaTeX and SVG output.

Forest Pass-Through (--forest)

to-tex --forest allows an externally generated Forest code file to be wrapped in the template. This is useful when you have manually adjusted Forest code and want to embed it in the document.

Special Character Handling

LaTeX/XML special characters and Newick conventions are normalized automatically:

  • Underscores (_) in node names are replaced with spaces.
  • LaTeX special characters ({ } \ # $ % & ~ ^) in node names, labels, comments, and visualization attributes are escaped for Forest output.
  • XML special characters (& < > " ') are escaped for SVG output.

This ensures that the generated files compile or render without manual cleanup.

Workflow Example

  1. Annotate the tree with visualization attributes:
necom nwk comment docs/data/catarrhini.nwk --lca Gorilla,Pan,Homo \
 --rec TeaRose --label Hominidae > annotated.nwk

A pre-annotated example is provided in docs/data/catarrhini_annotated.nwk.

  1. Generate the outputs:
necom nwk to-tex docs/data/catarrhini_annotated.nwk -o catarrhini.tex
necom nwk to-svg docs/data/catarrhini_annotated.nwk -o catarrhini.svg

  1. Compile the LaTeX document:

    tectonic catarrhini.tex

    The SVG can be opened directly in any modern web browser.

Requirements

Compiling to-tex output requires a LaTeX installation that includes:

  • fontspec
  • xeCJK (for East Asian characters)
  • forest

Tectonic is the recommended compiler, but latexmk -xelatex also works.

SVG output has no external dependencies.