plot_tree_radial: Plot a tree in radial layout.

In castor: Efficient Phylogenetics on Large Trees

Plot a tree in radial layout.

Description

Given a rooted phylogenetic tree, visualize the tree in radial form, i.e., with the root placed in the center and descending clades radiating outwards. Optionally, discrete tip metadata may be displayed in the form of colored rings around the tree.

Usage

plot_tree_radial(tree,
                file_path         = NULL,
                make_ultrametric  = FALSE,
                symmetric_arcs    = TRUE,
                opening           = 0,
                rotate            = 0,
                plot_width        = 5,
                plot_title        = NULL,
                show_scale_bar    = FALSE,
                align_tip_labels  = FALSE,
                tip_cex           = 0,
                node_cex          = 0,
                tip_label_cex     = NULL,
                scale_edge_widths = FALSE,
                base_edge_width   = 1,
                tip_color         = "black",
                node_color        = "black",
                edge_color        = "#00000080",
                node_arc_color    = "#00000080",
                root_edge_color   = "#00000080",
                tip_label_color   = "black",
                ring_colors       = NULL,
                ring_width        = 5,
                ring_border_width = 1,
                ring_border_color = "#FFFFFF",
                legend_colors     = NULL,
                legend_labels     = NULL)

Arguments

tree	A rooted tree of class "phylo". The root is assumed to be the unique node with no incoming edge.
file_path	Optional character, file path to save the plot to. Any existing file is silently replaced.
make_ultrametric	Logical, whether to make the tree ultrametric first, so that all tips appear at the same distance from the center. The transformation is done based on relative evolutionary divergences (Parks et al. 2018).
symmetric_arcs	Logical, whether nodes should appear in the middle of their arc. If FALSE, nodes are radially placed in the middle of their descending tips, which could result in nodes not being in the center of their arc.
opening	Optional numeric, opening angle of the tree in degrees, i.e., separating the two flanks of the tree. If 0, the tips will uniformly cover the whole circle. Must be between 0 and 360.
rotate	Optional numeric, angle (degrees) by which to rotate the whole plot, counter-clockwise. By default the tree is oriented such that the outer-most tip is placed on the right-most point of the circle, i.e., at "3'o clock".
plot_width	Plot width & height in inches, excluding margins. Only relevant if file_path is specified.
plot_title	Optional character, plot title.
show_scale_bar	Logical, whether to show a scale bar in the corner of the plot.
align_tip_labels	Logical, whether to align all tip labels on a single circle, rather than placing each tip label immediately adjacent to each tip. Only relevant for non-ultrametric trees, only if show_tip_labels=TRUE and only if no rings are shown (see ring_colors). If colored rings are shown, then tip labels are always aligned.
tip_cex	Numeric, circle rescaling for tips. If >0, tips are shown as circles.
node_cex	Numeric, circle rescaling for nodes. If >0, nodes are shown as circles.
tip_label_cex	Numeric, tip label rescaling. If 0, tip labels are not shown. If NULL, this is adjusted automatically to try to make tip labels fit.
scale_edge_widths	Logical, whether to scale the width (thickness) of each edge and node arc proportionally to the square root of the number of tips descending from it. If FALSE, all edges will have the same width.
base_edge_width	Numeric, base (smallest) width of edges, e.g. at the tips (and everywhere else if scale_edge_widths==FALSE).
tip_color	Either a single character or a character vector of length Ntips or an RGB tuple or an RGBA tuple, specifying tip colors & alpha. This vector must be synchronized with the tree tips.
node_color	Either a single character or a character vector of length Nnodes or an RGB tuple or an RGBA tuple, specifying node colors & alpha. This vector must be synchronized with the tree nodes.
edge_color	Either a single character or a character vector of length Nedges or an RGB tuple or an RGBA tuple, specifying edge colors & alpha. This vector must be synchronized with the tree edges, i.e., as specified in tree$edge or tree$edge.length.
node_arc_color	Either a single character or a character vector of length Nodes or an RGB tuple or an RGBA tuple, specifying node arc colors & alpha. This vector must be synchronized with the tree nodes.
root_edge_color	Color of the root edge, if applicable.
tip_label_color	Either a single character or a character vector of length Ntips or an RGB tuple or an RGBA tuple, specifying tip label colors & alpha. This vector must be synchronized with the tree tips.
ring_colors	Optional specification of discrete data to be visualized as multi-colored rings around the tree. Must be either a data.frame or a matrix of size Ntips x NC, specifying one or more multi-colored rings to show around the tree. The entries of ring_colors[] must be valid HEX color characters, with ring_colors[t,r] being the color for tip t on ring r. An entry of NULL or NA means no color segment is drawn for a tip, effectively keeping the background color. If ring_colors[] has row names, these will be matched to the tip labels, otherwise rows are assumed to already be synchronized with the tree's tips.
ring_width	Numeric, line width to use for colored rings around the tree. Only relevant if ring_colors is provided.
ring_border_width	Numeric, line width to use for the ring borders. A value of 0 means zero space between successive rings.
ring_border_color	Color to use for the ring borders, i.e., separating the rings from each other and from the tree.
legend_colors	Vector specifying colors to be defined in a legend. These can be for example colors in ring_colors[], or colors used for the tips & nodes & edges.
legend_labels	Optional character vector specifying labels to be given in a legend, synchronized with legend_colors[].

Details

The input tree may include multi-furcations (i.e. nodes with more than 2 children) as well as mono-furcations (i.e. nodes with only one child). If tree$edge.length is NULL, then all edges in the input tree are assumed to have length 1.

Value

This function returns no value. It either displays a plot (if file_path==NULL) or saves a plot to a file.

Author(s)

Stilianos Louca

References

D. H. Parks, M. Chuvochina et al. (2018). A proposal for a standardized bacterial taxonomy based on genome phylogeny. bioRxiv 256800. DOI:10.1101/256800

See Also

write_tree

Examples

# generate a random ultrametric tree
tree = generate_random_tree(list(birth_rate_intercept=1), max_tips=50, tip_basename="tip.")$tree

# plot in radial layout
castor::plot_tree_radial(tree           = tree,
                        show_scale_bar  = TRUE,
                        tip_cex         = 0.5,
                        node_cex        = 0)

castor documentation built on Aug. 25, 2025, 1:10 a.m.