Python API

tree_annotated_plot.plot

plot

plot(tree: str | Path | dict | TreeNode, chart: ChartInput, *, chart_strain_field: str, tree_strain_field: str, branch_length: Literal['div', 'num_date'], tree_size: int = 100, tree_location: TreeLocation | None = None, tree_line_width: float = 1.5, tree_node_size: float = 28, leader_line_width: float = 1.0, scale_bar: bool = False, branch_length_units: str | None = None, prune_tree_to_chart: bool = False, strict_version: bool = True) -> alt.HConcatChart | alt.VConcatChart

Return an Altair chart with a phylogenetic tree drawn alongside chart.

PlotConfig

The single source of truth for plot-parameter descriptions. The tree-annotated-plot CLI generates its options from this dataclass (see Command line), and the tree_annotated_plot.plot function accepts the same keyword arguments.

PlotConfig dataclass

Configuration for tree_annotated_plot.plot.

Each field's type annotation is Annotated[T, "<description>"]. The description is the canonical text that appears in the function's docstring, the click --help text, and the rendered Python API page.

chart_strain_field instance-attribute

chart_strain_field: Annotated[str, 'Required. The data-column name the chart\'s strain axis encodes (e.g. "strain" or "axis_label").']

tree_strain_field instance-attribute

tree_strain_field: Annotated[str, '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.']

branch_length instance-attribute

branch_length: Annotated[Literal['div', 'num_date'], 'Required. Which Auspice node attribute supplies branch lengths. "div" means divergence branch lengths; "num_date" means calendar dates.']

tree_size class-attribute instance-attribute

tree_size: Annotated[int, "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*."] = 100

tree_location class-attribute instance-attribute

tree_location: Annotated[TreeLocation | None, '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).'] = None

tree_line_width class-attribute instance-attribute

tree_line_width: Annotated[float, "Stroke width (px) for the tree's branch lines. Default 1.5."] = 1.5

tree_node_size class-attribute instance-attribute

tree_node_size: Annotated[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.'] = 28

leader_line_width class-attribute instance-attribute

leader_line_width: Annotated[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."] = 1.0

scale_bar class-attribute instance-attribute

scale_bar: Annotated[bool, '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.'] = False

branch_length_units class-attribute instance-attribute

branch_length_units: Annotated[str | None, '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.'] = None

prune_tree_to_chart class-attribute instance-attribute

prune_tree_to_chart: Annotated[bool, "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."] = False

strict_version class-attribute instance-attribute

strict_version: Annotated[bool, '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.'] = True

__init__

__init__(*, chart_strain_field: Annotated[str, 'Required. The data-column name the chart\'s strain axis encodes (e.g. "strain" or "axis_label").'], tree_strain_field: Annotated[str, '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.'], branch_length: Annotated[Literal['div', 'num_date'], 'Required. Which Auspice node attribute supplies branch lengths. "div" means divergence branch lengths; "num_date" means calendar dates.'], tree_size: Annotated[int, "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*."] = 100, tree_location: Annotated[TreeLocation | None, '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).'] = None, tree_line_width: Annotated[float, "Stroke width (px) for the tree's branch lines. Default 1.5."] = 1.5, tree_node_size: Annotated[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.'] = 28, leader_line_width: Annotated[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."] = 1.0, scale_bar: Annotated[bool, '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.'] = False, branch_length_units: Annotated[str | None, '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.'] = None, prune_tree_to_chart: Annotated[bool, "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."] = False, strict_version: Annotated[bool, '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.'] = True) -> None

Tree loading

load_auspice

load_auspice(source: str | Path | dict, *, tree_strain_field: str, branch_length: str = 'div', strict_version: bool = True) -> TreeNode

Load an Auspice JSON tree from a path or dict.

Parameters:

Name	Type	Description	Default
source	str | Path | dict	Path to an Auspice JSON file, or an already-parsed dict.	required
tree_strain_field	str	Where on each tip to find the strain identifier. The literal string "name" selects the tip's top-level name field; any other value X selects node_attrs[X] (auto-unwrapping the Auspice {"value": ...} convention). Dotted paths are not accepted.	required
branch_length	str	Which Auspice node attribute supplies branch lengths. "div" (default) reads node_attrs.div (a scalar absolute divergence from the root). "num_date" reads node_attrs.num_date.value (an absolute calendar position in years). In both cases the value is stored on each TreeNode.x and is used as-is by layout, segments, and pruning — they're branch-source-agnostic.	'div'
strict_version	bool	When True (default), raise ValueError if the Auspice JSON's top-level version field does not start with "v2". With False the same case becomes a warnings.warn. A missing version field always warns and proceeds.	True

TreeNode dataclass

A node in a phylogenetic tree.

name carries the resolved strain identifier for tips (the value at tree_strain_field). For internal nodes, name is the Auspice top-level name field — internal-node identity isn't used for chart-strain matching.

x is divergence from the root (read from node_attrs.div). y is set by :func:layout and is the integer index of the node's tip (for tips) or the midpoint of its descendants' tip indices (for internal nodes).

name instance-attribute

name: str

x instance-attribute

x: float

y class-attribute instance-attribute

y: float | None = None

children class-attribute instance-attribute

children: list['TreeNode'] = field(default_factory=list)

is_tip property

is_tip: bool