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).
--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. Default 0. Has no effect when
connect_leader_to_label is off. [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.