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 1.5.  [default: 1.5]
  --tree-node-size FLOAT          Area (px²) of the small filled circles drawn
                                  at each tip. Default 28. Setting
                                  tree_node_size=0 disables the tip-circle
                                  layer entirely.  [default: 28]
  --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. Chart
                                  strains not present in the tree are *always*
                                  fatal regardless of this flag — pruning
                                  would silently lose plot data.  [default:
                                  no-prune-tree-to-chart]
  --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]
  --help                          Show this message and exit.