TreeViz Class

pycirclizely.tree.TreeViz

TreeViz(
    tree_data: str | Path | Tree,
    *,
    format: str = "newick",
    outer: bool = True,
    align_leaf_label: bool = True,
    ignore_branch_length: bool = False,
    leaf_label_size: float = 12,
    leaf_label_rmargin: float = 2.0,
    reverse: bool = False,
    ladderize: bool = False,
    line_kws: dict[str, Any] | None = None,
    align_line_kws: dict[str, Any] | None = None,
    label_formatter: TextFormatter = None,
    track: Track
)

Phylogenetic Tree Visualization Class

Interface for changing tree properties and adding tree annotations in a track

Parameters:

Name	Type	Description	Default
tree_data	str | Path | Tree	Tree data (File|File URL|Tree Object|Tree String).	required
format	str	Tree format (newick|phyloxml|nexus|nexml|cdao).	'newick'
outer	bool	If True, plot tree on outer side. If False, plot tree on inner side.	True
align_leaf_label	bool	If True, align leaf label.	True
ignore_branch_length	bool	If True, ignore branch length for plotting tree.	False
leaf_label_size	float	Leaf label size.	12
leaf_label_rmargin	float	Leaf label radius margin.	2.0
reverse	bool	If True, reverse tree.	False
ladderize	bool	If True, ladderize tree.	False
line_kws	dict[str, Any] | None	Shape properties. https://plotly.com/python/reference/layout/shapes/	None
align_line_kws	dict[str, Any] | None	Shape properties. https://plotly.com/python/reference/layout/shapes/	None
label_formatter	TextFormatter	User-defined label text format function to change label text content.	None
track	Track	Track for tree visualization.	required

Methods:

Name	Description
get_target_xlim	Args:
highlight	Args:
load_tree	Args:
marker	Args:
search_target_node_name	Args:
set_node_label_props	Args:
set_node_line_props	Args:
show_node_info	Show node information as hovertext.

Attributes

all_node_labels cached property

all_node_labels: list[str]

All node labels

innode_labels cached property

innode_labels: list[str]

Internal node labels

leaf_labels cached property

leaf_labels: list[str]

Leaf labels

leaf_num cached property

leaf_num: int

Leaf number

max_tree_depth cached property

max_tree_depth: float

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

name2rect cached property

name2rect: dict[str, dict[str, float]]

Tree node name & rectangle dict

name2xr cached property

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

Tree node name & node xr coordinate dict

track property

track: Track

Track for tree visualization

tree property

tree: Tree

BioPython's Tree Object

Functions

get_target_xlim

get_target_xlim(
    query: str | list[str] | tuple[str],
) -> tuple[float, float]

Parameters:

Name	Type	Description	Default
query	str | list[str] | tuple[str]	Search query node name(s) for getting x limit. If multiple node names are set, MRCA(Most Recent Common Ancestor) node is set.	required

highlight

highlight(
    query: str | list[str] | tuple[str], **kwargs: Any
) -> None

Parameters:

Name	Type	Description	Default
query	str | list[str] | tuple[str]	Search query node name(s) for highlight. If multiple node names are set, MRCA(Most Recent Common Ancestor) node is set.	required
**kwargs	Any	Shape properties (e.g. fillcolor="red", line=dict(color="blue", width=2), opacity=0.5) See: https://plotly.com/python/reference/layout/shapes/	{}

load_tree staticmethod

load_tree(data: str | Path | Tree, format: str) -> Tree

Parameters:

Name	Type	Description	Default
data	str | Path | Tree	Tree data.	required
format	str	Tree format.	required

marker

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

Parameters:

Name	Type	Description	Default
query	str | list[str] | tuple[str]	Search query node name(s) for plotting marker. If multiple node names are set, MRCA(Most Recent Common Ancestor) node is set.	required
descendent	bool	If True, plot markers on target node's descendent as well.	True
hover_text	list[str] | None	Custom hover text for each marker. If None, generates default phylogenetic info.	None
**kwargs	Any	Scatter trace properties that override defaults. Common options include: - marker: dict with properties like size, color, symbol,.. - mode: 'markers', 'lines', 'markers+lines' - name: legend name for the trace	{}

search_target_node_name

search_target_node_name(
    query: str | list[str] | tuple[str],
) -> str

Parameters:

Name	Type	Description	Default
query	str | list[str] | tuple[str]	Search query node name(s). If multiple node names are set, MRCA(Most Recent Common Ancestor) node is set.	required

set_node_label_props

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

Parameters:

Name	Type	Description	Default
target_node_label	str	Target node label name.	required
**kwargs	Any	Annotation properties (e.g. dict(font=dict(size=12, color="black"))). https://plotly.com/python/reference/layout/annotations/.	{}

set_node_line_props

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

Parameters:

Name	Type	Description	Default
query	str | list[str] | tuple[str]	Search query node name(s) for coloring tree node line. If multiple node names are set, MRCA(Most Recent Common Ancestor) node is set.	required
descendent	bool	If True, set properties on target node's descendent as well.	True
apply_label_color	bool	If True & descendent=True & kwargs contain color keyword, apply node line color to node label color as well.	False
**kwargs	Any	Shape properties (e.g. dict(line=dict(color="red", width=1, dash="dash"))) See: https://plotly.com/python/reference/layout/shapes/	{}

show_node_info

show_node_info(
    *,
    node_type: Literal["all", "internal", "leaf"] = "all",
    hover_text_formatter: (
        Callable[[list[dict]], list[str]] | None
    ) = None,
    **kwargs: Any
) -> None

Show node information as hovertext.

Parameters:

Name	Type	Description	Default
node_type	Literal['all', 'internal', 'leaf']	Which nodes to show information for: - "all": All nodes - "internal": Only internal nodes (default) - "leaf": Only leaf nodes	'all'
hover_text_formatter	Callable[[list[dict]], list[str]] | None	User-defined function for hover text format.	None
**kwargs	Any	Scatter trace properties that override defaults. Note: The scatter points will be invisible by default (opacity=0).	{}