TreeViz Class

TreeViz

TreeViz(
    tree_data: str | Path | Tree,
    *,
    format: str = "newick",
    height: float = 0.5,
    width: float = 8,
    orientation: str = "right",
    align_leaf_label: bool = False,
    ignore_branch_length: bool = False,
    leaf_label_size: float = 12,
    innode_label_size: float = 0,
    show_auto_innode_label: bool = True,
    leaf_label_xmargin_ratio: float = 0.01,
    innode_label_xmargin_ratio: float = 0.01,
    reverse: bool = False
)

Phylogenetic Tree Visualization Class

PARAMETER	DESCRIPTION
tree_data	Tree data (File|File URL|Tree Object|Tree String) TYPE: str | Path | Tree
format	Tree format (newick|phyloxml|nexus|nexml|cdao) TYPE: str DEFAULT: 'newick'
height	Figure height per leaf node of tree TYPE: float DEFAULT: 0.5
width	Figure width TYPE: float DEFAULT: 8
orientation	Tree orientation (right|left) TYPE: str DEFAULT: 'right'
align_leaf_label	If True, align leaf label. TYPE: bool DEFAULT: False
ignore_branch_length	If True, Ignore branch length for plotting tree. TYPE: bool DEFAULT: False
leaf_label_size	Leaf label size TYPE: float DEFAULT: 12
innode_label_size	Internal node label size TYPE: float DEFAULT: 0
show_auto_innode_label	If True, show auto defined internal node label (e.g. N_1, N_2, ..., N_XX) TYPE: bool DEFAULT: True
leaf_label_xmargin_ratio	Leaf label x margin ratio TYPE: float DEFAULT: 0.01
innode_label_xmargin_ratio	Internal node label x margin ratio TYPE: float DEFAULT: 0.01
reverse	Plot tree in reverse order TYPE: bool DEFAULT: False

tree property

tree: Tree

BioPython's Tree Object

figsize property

figsize: tuple[float, float]

Figure size

xlim property

xlim: tuple[float, float]

Axes xlim

ylim property

ylim: tuple[float, float]

Axes ylim

leaf_labels cached property

leaf_labels: list[str]

Leaf labels

innode_labels cached property

innode_labels: list[str]

Internal node labels

all_node_labels cached property

all_node_labels: list[str]

All node labels

max_tree_depth cached property

max_tree_depth: float

Max tree depth (root -> leaf max branch length)

name2xy cached property

name2xy: dict[str, tuple[float, float]]

Tree node name & node xy coordinate dict (alias for name2xy_right)

name2xy_right cached property

name2xy_right: dict[str, tuple[float, float]]

Tree node name & node right xy coordinate dict

name2xy_center cached property

name2xy_center: dict[str, tuple[float, float]]

Tree node name & node center xy coordinate dict

name2xy_left cached property

name2xy_left: dict[str, tuple[float, float]]

Tree node name & node left xy coordinate dict

name2rect cached property

name2rect: dict[str, Rectangle]

Tree node name & rectangle dict

ax property

ax: Axes

Plot axes

Can't access ax property before calling tv.plotfig() method

show_branch_length

show_branch_length(
    *,
    size: int = 8,
    xpos: str = "center",
    ypos: str = "top",
    xmargin_ratio: float = 0.01,
    ymargin_ratio: float = 0.05,
    label_formatter: Callable[[float], str] | None = None,
    **kwargs
) -> None

Show branch length text label on each branch

PARAMETER	DESCRIPTION
size	Text size TYPE: int DEFAULT: 8
xpos	X position of plot text (left|center|right) TYPE: str DEFAULT: 'center'
ypos	Y position of plot text (top|center|bottom) TYPE: str DEFAULT: 'top'
xmargin_ratio	Text x margin ratio. If xpos = center, this param is ignored. TYPE: float DEFAULT: 0.01
ymargin_ratio	Text y margin ratio. If ypos = center, this param is ignored. TYPE: float DEFAULT: 0.05
label_formatter	User-defined branch length value label format function (e.g. lambda v: f"{v:.3f}") TYPE: Callable[[float], str] | None DEFAULT: None
**kwargs	Text properties (e.g. color="red", bbox=dict(color="skyblue"), ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict DEFAULT: {}

show_confidence

show_confidence(
    *,
    size: int = 8,
    xpos: str = "center",
    ypos: str = "bottom",
    xmargin_ratio: float = 0.01,
    ymargin_ratio: float = 0.05,
    label_formatter: Callable[[float], str] | None = None,
    **kwargs
) -> None

Show confidence text label on each branch

PARAMETER	DESCRIPTION
size	Text size TYPE: int DEFAULT: 8
xpos	X position of plot text (left|center|right) TYPE: str DEFAULT: 'center'
ypos	Y position of plot text (top|center|bottom) TYPE: str DEFAULT: 'bottom'
xmargin_ratio	Text x margin ratio. If xpos = center, this param is ignored. TYPE: float DEFAULT: 0.01
ymargin_ratio	Text y margin ratio. If ypos = center, this param is ignored. TYPE: float DEFAULT: 0.05
label_formatter	User-defined confidence value label format function (e.g. lambda v: f"{v:.3f}") TYPE: Callable[[float], str] | None DEFAULT: None
**kwargs	Text properties (e.g. color="red", bbox=dict(color="skyblue"), ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict DEFAULT: {}

show_scale_axis

show_scale_axis(*, ticks_interval: float | None = None, ypos: float = 0) -> None

Show scale axis

PARAMETER	DESCRIPTION
ticks_interval	Ticks interval. If None, interval is automatically defined. TYPE: float | None DEFAULT: None
ypos	Y position of axis. TYPE: float DEFAULT: 0

show_scale_bar

show_scale_bar(
    *,
    scale_size: float | None = None,
    text_size: float = 8,
    loc: str = "lower left",
    label_top: bool = False
) -> None

Show scale bar

PARAMETER	DESCRIPTION
scale_size	Scale size. If None, size is automatically defined. TYPE: float | None DEFAULT: None
text_size	Text label size TYPE: float | None DEFAULT: 8
loc	Bar location (e.g. lower left, upper left) TYPE: str DEFAULT: 'lower left'
label_top	If True, plot label on top. If False, plot label on bottom. TYPE: bool DEFAULT: False

highlight

highlight(
    query: str | list[str] | tuple[str],
    color: str,
    *,
    alpha: float = 0.5,
    area: str = "branch-label",
    **kwargs
) -> None

Plot highlight for target node

PARAMETER	DESCRIPTION
query	Search query node name(s) for highlight. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
color	Highlight color TYPE: str
alpha	Highlight color alpha(transparancy) value TYPE: float DEFAULT: 0.5
area	Highlight area (branch|branch-label|full) TYPE: str DEFAULT: 'branch-label'
**kwargs	Rectangle properties (e.g. alpha=0.5, ec="grey", lw=1.0, ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.Rectangle.html TYPE: dict DEFAULT: {}

annotate

annotate(
    query: str | list[str] | tuple[str],
    label: str,
    *,
    text_size: float = 10,
    text_color: str = "black",
    text_orientation: str = "horizontal",
    line_color: str = "black",
    xmargin_ratio: float = 0.01,
    align: bool = False,
    text_kws: dict[str, Any] | None = None,
    line_kws: dict[str, Any] | None = None
) -> None

Annotate tree clade with line & text label

PARAMETER	DESCRIPTION
query	Search query node name(s) for annotate. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
label	Label name TYPE: str
text_size	Text size TYPE: float DEFAULT: 10
text_color	Text color TYPE: str DEFAULT: 'black'
text_orientation	Text orientation (horizontal|vertical) TYPE: str DEFAULT: 'horizontal'
line_color	Line color TYPE: str DEFAULT: 'black'
xmargin_ratio	X margin ratio TYPE: float DEFAULT: 0.01
align	If True, annotate position is aligned to rightmost edge. TYPE: bool DEFAULT: False
text_kws	Text properties https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict[str, Any] | None DEFAULT: None
line_kws	Axes.plot properties (e.g. dict(lw=2.0, ls="dashed", ...)) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html TYPE: dict[str, Any] | None DEFAULT: None

marker

marker(
    query: str | list[str] | tuple[str],
    marker: str = "o",
    *,
    size: int = 6,
    descendent: bool = False,
    **kwargs
) -> None

Plot marker on target node(s)

PARAMETER	DESCRIPTION
query	Search query node name(s) for plotting marker. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
marker	Marker type (e.g. o, s, D, P, *, x, d, ^, v, <, >) https://matplotlib.org/stable/api/markers_api.html TYPE: str DEFAULT: 'o'
size	Marker size TYPE: int DEFAULT: 6
descendent	If True, plot markers on target node's descendent as well. TYPE: bool DEFAULT: False
**kwargs	Axes.scatter properties (e.g. color="red", ec="black", alpha=0.5, ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.scatter.html TYPE: dict DEFAULT: {}

link

link(
    query1: str | list[str] | tuple[str],
    query2: str | list[str] | tuple[str],
    *,
    pos1: str = "center",
    pos2: str = "center",
    color: str = "red",
    linestyle: str = "dashed",
    arrowstyle: str = "-|>",
    connectionstyle: str = "arc3,rad=0",
    **kwargs
) -> None

Plot link line between target nodes

PARAMETER	DESCRIPTION
query1	Search query node name(s) for setting link start node. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
query2	Search query node name(s) for setting link end node. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
pos1	Link start node branch position1 (left|center|right) TYPE: str DEFAULT: 'center'
pos2	Link end node branch position2 (left|center|right) TYPE: str DEFAULT: 'center'
color	Link line color TYPE: str DEFAULT: 'red'
linestyle	Line line style (e.g. dotted, dashdot, solid) TYPE: str DEFAULT: 'dashed'
arrowstyle	Arrow style (e.g. -, ->, <->, <|-|>) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.ArrowStyle.html TYPE: str DEFAULT: '-|>'
connectionstyle	Connection style (e.g. arc3,rad=0.2, arc3,rad=-0.5) https://matplotlib.org/stable/gallery/userdemo/connectionstyle_demo.html TYPE: str DEFAULT: 'arc3,rad=0'
**kwargs	PathPatch properties (e.g. lw=0.5, alpha=0.5, zorder=0, ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.patches.PathPatch.html TYPE: dict DEFAULT: {}

text_on_branch

text_on_branch(
    query: str | list[str] | tuple[str],
    text: str,
    *,
    size: int = 8,
    xpos: str = "right",
    ypos: str = "top",
    xmargin_ratio: float = 0.01,
    ymargin_ratio: float = 0.05,
    **kwargs
) -> None

Plot text on branch of target node

PARAMETER	DESCRIPTION
query	Search query node name(s) for plotting text. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
text	Text content TYPE: str
size	Text size TYPE: int DEFAULT: 8
xpos	X position of plot text (left|center|right) TYPE: str DEFAULT: 'right'
ypos	Y position of plot text (top|center|bottom) TYPE: str DEFAULT: 'top'
xmargin_ratio	Text x margin ratio. If xpos = center, this param is ignored. TYPE: float DEFAULT: 0.01
ymargin_ratio	Text y margin ratio. If ypos = center, this param is ignored. TYPE: float DEFAULT: 0.05
**kwargs	Text properties (e.g. color="red", bbox=dict(color="skyblue"), ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict DEFAULT: {}

text_on_node

text_on_node(
    query: str | list[str] | tuple[str], text: str, *, size: int = 8, **kwargs
) -> None

Plot text on target node

PARAMETER	DESCRIPTION
query	Search query node name(s) for plotting text. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
text	Text content TYPE: str
size	Text size TYPE: int DEFAULT: 8
**kwargs	Text properties (e.g. color="red", bbox=dict(color="skyblue"), ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict DEFAULT: {}

set_node_label_props

set_node_label_props(target_node_label: str, **kwargs) -> None

Set tree node label properties

PARAMETER	DESCRIPTION
target_node_label	Target node label name TYPE: str
kwargs	Text properties (e.g. color="red", ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.text.html TYPE: dict DEFAULT: {}

set_node_line_props

set_node_line_props(
    query: str | list[str] | tuple[str], *, descendent: bool = True, **kwargs
) -> None

Set tree node line properties

PARAMETER	DESCRIPTION
query	Search query node name(s) for coloring tree node line. If multiple node names are set, MRCA(Most Recent Common Ancester) node is set. TYPE: str | list[str] | tuple[str]
descendent	If True, set properties on target node's descendent as well. TYPE: bool DEFAULT: True
**kwargs	Axes.plot properties (e.g. color="blue", lw=2.0, ls="dashed", ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html TYPE: dict DEFAULT: {}

set_title

set_title(label: str, **kwargs) -> None

Set title

PARAMETER	DESCRIPTION
label	Title text label TYPE: str
**kwargs	Axes.set_title properties (e.g. size=12, color="red", ...) https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.set_title.html TYPE: dict DEFAULT: {}

update_plot_props

update_plot_props(
    *,
    tree_line_kws: dict[str, Any] | None = None,
    tree_align_line_kws: dict[str, Any] | None = None
) -> None

Update plot properties

PARAMETER	DESCRIPTION
tree_line_kws	Axes.plot properties (e.g. dict(color="red", lw=0.5, ...)) By default, color="black", lw=1, clip_on=False are set. https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html TYPE: dict[str, Any] DEFAULT: None
tree_align_line_kws	Axes.plot properties (e.g. dict(color="red", ls="dashed", ...)) By default, lw=0.5, ls="dashed", alpha=0.5, clip_on=False are set. https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.plot.html TYPE: dict[str, Any] DEFAULT: None

plotfig

plotfig(*, dpi=100, ax: Axes | None = None) -> Figure

Plot figure

PARAMETER	DESCRIPTION
dpi	Figure DPI TYPE: int DEFAULT: 100
ax	Matplotlib axes for plotting. If None, figure & axes are newly created. TYPE: Axes | None DEFAULT: None

RETURNS	DESCRIPTION
figure	Matplotlib figure TYPE: Figure

savefig

savefig(savefile: str | Path, *, dpi: int = 100, pad_inches: float = 0.1) -> None

Save figure to file

tv.savefig("result.png") is alias for tv.plotfig().savefig("result.png")

PARAMETER	DESCRIPTION
savefile	Save file (*.png|*.jpg|*.svg|*.pdf) TYPE: str | Path
dpi	DPI TYPE: int DEFAULT: 100
pad_inches	Padding inches TYPE: float DEFAULT: 0.1