Displays a tree as a graph, as text or SVG.

Synopsis
--------

nw_display [options] <tree filename|->

Input
-----

Argument is the name of the file containing one or more trees,
or '-' (in which case the tree is read on stdin).

Output
------

Outputs a graph representing the tree, either as text (default) or
as SVG (option -s). Underscores in labels are replaced with spaces.
Trees with no branch lengths are taken to be cladograms and are
drawn with leaves aligned. Otherwise, the tree is assumed to be a
phylogram: branch lengths are honored and a scale bar is drawn.

SVG graphics can be converted to other formats with converters
such as Inkscape (e.g. to PDF) or ImageMagick (e.g. to PNG or JPEG).
Inkscape is available from www.inkscape.org and ImageMagick from
www.imagemagick.org.

Options
-------

    -a <number>: rotate all labels by this amount (radians, default: 0)
       [only SVG radial]
    -A <number>: rotate left-side labels by this amount (radians,
       default: 0.0349 (=~ 2°)) [only SVG radial]
    -b <string>: CSS for branch length labels. [only SVG]
       Default: 'font-size:small;font-family:sans'.
       setting 'opacity:0' disables printing of branch lengths.
    -c <filename>: use specified file as CSS map [only SVG]. A CSS map
       is a text file which specifies a style (CSS) for a clade.
       Each line has the following structure:
       <CSS> <flag> <label>+
       <CSS> is a valid CSS style specification (no spaces allowed)
       e.g. 'font-size:small;font-family:italics;stroke:green'.
       <flag> is either 'Individual' or 'Clade' (case is not important, can
       be abbreviated down to 'I' or 'C'). If set to 'Clade', the style is
       applied to the clade defined by the labels. If 'Individual', the
       style is applied to each node individually.
       <label>+ is a nonempty, whitespace-separated list of Newick labels
       (spaces are allowed IFF the label is enclosed in ''). If a label
       matches more than one node, all matching nodes are used.
       Default: no CSS map, whole tree is black (unless specified otherwise
       via option -d).
       <CSS>, <flag>, and <labels>+ are separated by whitespace.
       The following specifies red stroke for a clade defined by A, B and C;
       and 2-pixel wide, blue stroke for individual nodes D, E, and F:
       stroke:red			Clade	A B C
       stroke:blue;stroke-width:2	I	D E F
       If no colormap is specified, the default is (but see option -d):
       stroke:black;fill:none;stroke-width:1;stroke-linecap:round
    -d <string>: CSS for 'plain' tree nodes (i.e., unless overridden by -c)
       [only SVG]
       Default: stroke:black;fill:none;stroke-width:1;stroke-linecap:round
    -h: prints this message and exits
    -i <string>: CSS for inner node labels. [only SVG]
       Default: 'font-size:small;font-family:sans'.
       setting 'visibility:hidden' disables printing of inner node labels.
    -I <char> sets the position of the inner node label. Valid options are
       'l' (near the leaves), 'm' (middle) or 'r' (near the root). Default
       is 'l'.
    -l <string>: CSS for leaf node labels. [only SVG]
       Default: 'font-size:medium;font-family:sans'.
       setting 'visibility:hidden' disables printing of leaf node labels.
       Note: if you change this, you will probably need to adjust the
       space allocated to leaf labels - see option -W.
    -n <number> add this number of pixels to the horizontal position of
       node labels. [SVG only]
    -o <filename>: use specified file as ornament map. Works like the CSS
       map (see option -c), except that it specifies arbitrary SVG snippets
       instead of CSS styles. For example, the following
       "<circle style='fill:red' r='5'>" Clade A B C
       will draw a red circle of radius 5 at the root of the clade defined
       by nodes A, B, and C. Keyword 'Individual' is also accepted and
       works like for CSS.
    -R <integer>: use that many pixels for the root [only SVG]
    -r: draw a radial tree (default: orthogonal) [only SVG]
    -s: output graph as SVG (default: ASCII graphics). All output is on
       stdout, so if there is more than one tree, stdout will be a
       concatenation of SVG documents. These can be split into individual
       files with the csplit(1) command:

       $ nw_display -s many_trees.nw > multiple_svg
       $ csplit -zs -f tree_ -b '%02d.svg' multiple_svg '/<?xml/' {*}

       will generate as many SVG files as there are Newick trees in
       many_trees.nw. The files will be named tree_01.svg, tree_02.svg, etc.
    -S: suppress scale bar (ignored for cladograms)
    -t: set the zero of the scale at the maximum depth instead of the root.
       This is useful when the branch lengths are in time units: zero marks
       the present, and the scale shows the age of the ancestral nodes.
    -u <string>: string is used as unit name for scale bar (ignored
       if no scale bar is drawn).
    -U <URL_filename>: use specified URL map [only SVG]. A URL map
       is a text file which specifies a URL for a label.
       Each line has the following structure:
       <label> <URL>
       Clicking on a label will follow the link (if any).
    -v <number>: number of pixels between leaves (default: 40) [only SVG
       orthogonal]
    -w <number>: graph should be no wider than <number>, measured in
       characters for text and pixels for SVG. Defaults: 80 (text),
       300 (SVG)
    -W <number>: use this as an estimate of the width of a leaf label
       character (in pixels) [only SVG]. This affects the space left for
       the tree nodes. Default: 5.0 You will probably need this if you
       change the leaf label font properties (option -l), especially size.
       You will probably need trial and error to find the right value.

LibXML
......

If LibXML is being used, the handling of ornaments (-o) is more elaborate.
See the tutorial, section 2.2 (displaying) for details.
This executable uses LibXML2.

Examples
--------

# display tree as ASCII
$ nw_display data/catarrhini

# display tree as SVG, using a color map
$ nw_display -s -c data/color.map data/catarrhini

# ditto, convert to other graphics formats
$ nw_display -s -c data/color.map data/catarrhini > catarrhini.svg
$ convert catarrhini.svg catarrhini.png	# PNG, with ImageMagick
$ convert catarrhini.svg catarrhini.jpeg	# JPEG, with ImageMagick
$ inkscape -z -f catarrhini.svg -A catarrhini.pdf # PDF, with Inkscape

# the same; no branch lengths
$ nw_display -s -b 'visibility:hidden' -c data/color.map data/catarrhini

# radial tree, leaf labels in italics
$ nw_display -s -r -l 'font-style:italics' data/catarrhini