A phylogenetic tree displays hierarchical relationships between taxa using branches and nodes. Supports rectangular, slanted, and circular branch styles; phylogram (branch-length-based) and cladogram (uniform-depth) modes; and clade coloring.
Constructors
from_newick
Parse a Newick-format string into a PhyloTree.
pub fn from_newick(s: &str) -> Self
Newick string with optional branch lengths and support values
A:1.0), support values on internal nodes, and arbitrarily nested subtrees.
Example:
use kuva::plot::PhyloTree;
let tree = PhyloTree::from_newick("((A:1.0,B:1.5)95:0.5,C:2.0);");
from_edges
Build a tree from (parent_label, child_label, branch_length) edges.
pub fn from_edges<S: AsRef<str>>(edges: &[(S, S, f64)]) -> Self
Edges as (parent, child, branch_length) triplets
let edges = vec![
("root", "A", 1.0),
("root", "B", 1.5),
("root", "C", 2.0),
];
let tree = PhyloTree::from_edges(&edges);
from_distance_matrix
Build a tree by UPGMA clustering of a symmetric distance matrix.
pub fn from_distance_matrix(labels: &[&str], dist: &[Vec<f64>]) -> Self
Leaf labels (one per row/column)
N×N symmetric distance matrix
let labels = vec!["A", "B", "C"];
let dist = vec![
vec![0.0, 1.0, 2.0],
vec![1.0, 0.0, 1.5],
vec![2.0, 1.5, 0.0],
];
let tree = PhyloTree::from_distance_matrix(&labels, &dist);
from_linkage
Build a tree from a scipy / R linkage matrix.
pub fn from_linkage(labels: &[&str], linkage: &[[f64; 4]]) -> Self
Leaf labels (one per original element)
Linkage matrix where each row is [left_idx, right_idx, distance, n_leaves]
0..n-1 are the original leaves; n.. are internal nodes.
Example:
let labels = vec!["A", "B", "C"];
let linkage = vec![
[0.0, 1.0, 0.5, 2.0], // merge A and B at distance 0.5
[2.0, 3.0, 1.0, 3.0], // merge (A,B) and C at distance 1.0
];
let tree = PhyloTree::from_linkage(&labels, &linkage);
Orientation
with_orientation
Set which axis the root appears on.
pub fn with_orientation(self, o: TreeOrientation) -> Self
Tree orientation (default: TreeOrientation::Left)
TreeOrientation::Left — root at left, leaves at right (default)TreeOrientation::Right — root at right, leaves at leftTreeOrientation::Top — root at top, leaves at bottomTreeOrientation::Bottom — root at bottom, leaves at top
Example:
use kuva::plot::{PhyloTree, TreeOrientation};
let tree = PhyloTree::from_newick(newick_str)
.with_orientation(TreeOrientation::Top);
Branch Style
with_branch_style
Set how branches are drawn between parent and child.
pub fn with_branch_style(self, s: TreeBranchStyle) -> Self
Branch style (default: TreeBranchStyle::Rectangular)
TreeBranchStyle::Rectangular — right-angle elbows at parent depth (default)TreeBranchStyle::Slanted — single diagonal line from parent to childTreeBranchStyle::Circular — polar/radial projection
Example:
use kuva::plot::{PhyloTree, TreeBranchStyle};
let tree = PhyloTree::from_newick(newick_str)
.with_branch_style(TreeBranchStyle::Circular);
Phylogram Mode
with_phylogram
Enable phylogram mode: use branch lengths for the depth axis.
pub fn with_phylogram(self) -> Self
let tree = PhyloTree::from_newick(newick_str)
.with_phylogram();
Color Configuration
with_branch_color
Set the color for all branches.
pub fn with_branch_color<S: Into<String>>(self, c: S) -> Self
CSS color string (default: "black")
with_leaf_color
Set the text color for leaf labels.
pub fn with_leaf_color<S: Into<String>>(self, c: S) -> Self
CSS color string (default: "black")
with_clade_color
Color the entire subtree rooted at node_id with color.
pub fn with_clade_color<S: Into<String>>(self, node_id: usize, color: S) -> Self
Root node ID of the clade to color
let tree = PhyloTree::from_newick(newick_str)
.with_clade_color(5, "steelblue")
.with_clade_color(8, "firebrick");
Support Values
with_support_threshold
Show support values >= threshold.
pub fn with_support_threshold(self, t: f64) -> Self
Minimum support value to display (e.g. 0.7 for 70% bootstrap)
let tree = PhyloTree::from_newick(newick_str)
.with_support_threshold(0.7); // show bootstrap >= 70%
Legend
with_legend
Enable a legend.
pub fn with_legend<S: Into<String>>(self, label: S) -> Self
Helper Methods
leaf_labels_top_to_bottom
Return leaf labels in the top-to-bottom render order (post-order DFS, left children first).
pub fn leaf_labels_top_to_bottom(&self) -> Vec<String>
Vec<String>
Use this to set y_categories on a side-by-side Heatmap for row alignment.
Example:
let tree = PhyloTree::from_newick(newick_str);
let row_order = tree.leaf_labels_top_to_bottom();
// Use row_order for heatmap y-axis to align with tree leaves
Full Example
use kuva::plot::{PhyloTree, TreeOrientation, TreeBranchStyle};
use kuva::backend::svg::SvgBackend;
use kuva::render::render::render_multiple;
use kuva::render::layout::Layout;
use kuva::render::plots::Plot;
let newick = "((human:0.3,chimp:0.3)100:0.5,(mouse:0.6,rat:0.6)98:0.4)95:0.2;";
let tree = PhyloTree::from_newick(newick)
.with_phylogram()
.with_orientation(TreeOrientation::Left)
.with_branch_style(TreeBranchStyle::Rectangular)
.with_support_threshold(0.9)
.with_clade_color(1, "steelblue"); // color the (human, chimp) clade
let plots = vec![Plot::PhyloTree(tree)];
let layout = Layout::auto_from_plots(&plots)
.with_title("Mammalian Phylogeny");
let svg = SvgBackend.render_scene(&render_multiple(plots, layout));
std::fs::write("phylo.svg", svg).unwrap();