Command line¶
The tree-annotated-plot command pairs a saved Vega-Lite chart spec
(JSON or HTML) with an Auspice JSON tree and writes the combined plot
to disk.
The configuration options below are auto-generated from
PlotConfig, so
descriptions and CLI --help text are guaranteed to match.
Quickstart¶
tree-annotated-plot \
--tree h3n2.auspice.json \
--chart titers.json \
--output combined.html \
--chart-strain-field axis_label \
--tree-strain-field derived_haplotype \
--branch-length div
The output's format is dispatched on the file extension: .html,
.json, .png, .svg, .pdf are all accepted.
Reference¶
tree-annotated-plot¶
Plot a phylogenetic tree alongside a Vega-Lite chart whose categorical axis is reordered to match the tree's tip order. Save the result as HTML / JSON / PNG / SVG / PDF (format is dispatched on --output's extension).
Usage:
tree-annotated-plot [OPTIONS]
Options:
--tree FILE Phylogenetic tree in Auspice JSON v2 format.
The CLI accepts a file path; the Python API
additionally accepts a parsed dict or a pre-
built `tree_annotated_plot.TreeNode`.
[required]
--chart FILE Vega-Lite chart whose strain axis the tree
will annotate. The CLI accepts a saved spec
on disk — either *.json (canonical) or
*.html (extracted from altair's default save
template). The Python API additionally
accepts a live `altair.Chart`-or-subclass
object or a parsed spec dict. Must encode
`chart_strain_field` on `x` or `y`.
[required]
--output FILE Where to save the combined plot. Format
inferred from extension: .html, .json, .png,
.svg, .pdf. [required]
--chart-strain-field TEXT Required. The data-column name the chart's
strain axis encodes (e.g. "strain" or
"axis_label"). [required]
--tree-strain-field TEXT Required. Where on each tree tip to find the
strain identifier. The literal string "name"
selects the top-level Auspice node `name`
field; any other value X selects
node_attrs[X] (auto-unwrapping the Auspice
{"value": ...} convention). Dotted paths are
not accepted. [required]
--branch-length [div|num_date] Required. Which Auspice node attribute
supplies branch lengths. "div" means
divergence branch lengths; "num_date" means
calendar dates. [required]
--tree-size INTEGER Size in pixels of tree depth. For vertical
layout (chart strain on `y`) this is the
tree panel's *width*; for horizontal layout
(chart strain on `x`) this is the tree
panel's *height*. [default: 100]
--tree-location [left|right|top|bottom]
Which side of the chart to draw the tree on.
Defaults to the side with the strain-axis
labels ("left" for y-encoded strain,
"bottom" for x-encoded). Other valid values:
"right" (y-encoded), "top" (x-encoded).
--spacing INTEGER Pixels of blank space between the tree panel
and the chart panel. Default 0, which butts
the two together. Distinct from
`shift_tree_loc`, which moves the tree
within its own panel by resizing the label
strip; `spacing` sets the gap between the
panels and applies whether or not
`connect_leader_to_label` is on. [default:
0]
--tree-line-width FLOAT Stroke width (px) for the tree's branch
lines. Default 2. [default: 2.0]
--tree-node-size FLOAT Area (px²) of the small filled circles drawn
at each tip. Default 45. Setting
tree_node_size=0 disables the tip-circle
layer entirely. [default: 45]
--leader-line-width FLOAT Stroke width (px) for the dashed leader
lines that connect each tip's branch
endpoint to the strain row when the branch
doesn't extend all the way to branch_max.
Default 1.0. Setting leader_line_width=0
disables the leader-line layer entirely.
[default: 1.0]
--scale-bar / --no-scale-bar Off by default. When on, adds a small bar in
the tree panel showing the branch-length
scale. Tip-row alignment with the chart is
preserved. [default: no-scale-bar]
--branch-length-units TEXT Used only when scale_bar is on and
branch_length="div": the unit string pasted
after the bar's numeric length (e.g.
"substitutions/site"). None renders
unitless. For branch_length="num_date" the
label is always in years/months and this
argument is ignored.
--prune-tree-to-chart / --no-prune-tree-to-chart
When off (default), tree tips not present in
the chart's strain set are a fatal error.
When on, those tips (and any internal nodes
whose subtrees become empty) are dropped
before drawing, with single-child internals
collapsed into their kept child. [default:
no-prune-tree-to-chart]
--prune-chart-to-tree / --no-prune-chart-to-tree
When off (default), chart strains not
present in the tree are a fatal error. When
on, chart rows whose `chart_strain_field`
value isn't a tree tip are filtered out
before drawing. [default: no-prune-chart-
to-tree]
--strict-version / --no-strict-version
When on (default), known-stale specs raise:
Vega-Lite 5 or earlier, and Auspice JSON
whose `version` is not v2. When off, those
become warnings and parsing proceeds.
[default: strict-version]
--connect-leader-to-label / --no-connect-leader-to-label
Off (default): the chart's strain-axis
labels are kept as the user wrote them and
dashed leader lines stop at the tree panel's
chart-facing edge. On: leaders extend all
the way to the labels — which requires
moving the labels off the chart's strain
axis and into the tree panel, so the chart's
strain-axis labels, ticks, axis line, and
title are SUPPRESSED (any user-supplied
`axis=...` is overridden) and replacement
labels are rendered alongside the tree.
Label widths are estimated; for crowded
charts tune `strain_label_font_size` or
`shift_tree_loc`. [default: no-connect-
leader-to-label]
--strain-label-font-size FLOAT Font size (px) for the strain text labels
rendered in the tree panel when
`connect_leader_to_label` is on. [default:
10.0]
--strain-label-font-weight [normal|bold]
Font weight for the strain text labels
rendered in the tree panel when
`connect_leader_to_label` is on. [default:
normal]
--shift-tree-loc INTEGER Pixels by which to shift the tree toward
(positive) or away from (negative) the
chart, by resizing the label strip inside
the tree panel. Default 0. Has no effect
when connect_leader_to_label is off; to set
the gap between the tree and chart panels
use `spacing`. [default: 0]
--color-tree-by TEXT Color the tree by an Auspice attribute. Pass
a node_attrs key (e.g. "subclade"), or
"genotype:<GENE>:<SITE>" /
"genotype:<GENE>:<SITE1>,<SITE2>,..." (e.g.
"genotype:HA1:158" or
"genotype:HA1:158,189") to color by the
inferred genotype state at a site or
haplotype across sites. A categorical legend
is drawn below the plot; missing values are
gray. None (default) leaves the tree black.
--tree-color-scale COLOR_SCALE Hardcoded color scale that overrides the
default coloring. Keys are category labels,
values are colors (any Vega-Lite-compatible
string — e.g. hex codes). The legend order
follows the order keys appear here. The keys
must match the tree's categories one-to-one
(extra or missing keys are an error).
"unknown" is always gray and must not be
specified. For genotype/haplotype colorings,
the category strings include the site number
(e.g. "K158" or "K158/E189"); a mismatch
error lists the actual tree categories. CLI
form: "value1=#hex1,value2=#hex2,...".
--tree-color-legend-format JSON_DICT
Vega-Lite Legend properties to apply to the
tree-coloring legend. Pass any subset of the
keys at https://vega.github.io/vega-
lite/docs/legend.html#properties as a Python
dict (e.g. `{"orient": "left",
"labelFontSize": 13, "titleFontSize": 13}`).
Common keys: "orient" (default "bottom"),
"direction", "columns", "padding", "offset",
"labelFontSize", "titleFontSize". Smart
default: when "orient" is "left" or "right"
and you have not set "columns" or
"direction", "columns" is forced to 1 so
entries stack vertically. None (default)
leaves Vega-Lite's defaults. Has no effect
when `color_tree_by` is None. CLI form: a
JSON object string (quote the whole
argument), e.g.
'{"orient":"left","labelFontSize":13}'.
--tree-color-legend-show / --no-tree-color-legend-show
Whether to render the tree-coloring legend.
On (default) shows it. Off hides the legend
entirely while keeping the tree colored. Has
no effect when `color_tree_by` is None.
[default: tree-color-legend-show]
--scale-bar-font-size FLOAT Font size (px) for the tree's scale bar
label. Default 10. Has no effect when
`scale_bar` is off. [default: 10.0]
-h, --help Show this message and exit.