Plots the distribution of values associated with a taxonomic classification/heirarchy. Taxonomic classifications can have multiple roots, resulting in multiple trees on the same plot. A tree consists of elements, element properties, conditions, and mapping properties which are represented as parameters in the heat_tree object. The elements (e.g. nodes, edges, lables, and individual trees) are the infrastructure of the heat tree. The element properties (e.g. size and color) are characteristics that are manipulated by various data conditions and mapping properties. The element properties can be explicitly defined or automatically generated. The conditions are data (e.g. taxon statistics, such as abundance) represented in the taxmap/metacoder object. The mapping properties are parameters (e.g. transformations, range, interval, and layout) used to change the elements/element properties and how they are used to represent (or not represent) the various conditions.
heat_tree(...)# S3 method for Taxmap
heat_tree(.input, ...)
# S3 method for default
heat_tree(
taxon_id,
supertaxon_id,
node_label = NA,
edge_label = NA,
tree_label = NA,
node_size = 1,
edge_size = node_size,
node_label_size = node_size,
edge_label_size = edge_size,
tree_label_size = as.numeric(NA),
node_color = "#999999",
edge_color = node_color,
tree_color = NA,
node_label_color = "#000000",
edge_label_color = "#000000",
tree_label_color = "#000000",
node_size_trans = "area",
edge_size_trans = node_size_trans,
node_label_size_trans = node_size_trans,
edge_label_size_trans = edge_size_trans,
tree_label_size_trans = "area",
node_color_trans = "area",
edge_color_trans = node_color_trans,
tree_color_trans = "area",
node_label_color_trans = "area",
edge_label_color_trans = "area",
tree_label_color_trans = "area",
node_size_range = c(NA, NA),
edge_size_range = c(NA, NA),
node_label_size_range = c(NA, NA),
edge_label_size_range = c(NA, NA),
tree_label_size_range = c(NA, NA),
node_color_range = quantative_palette(),
edge_color_range = node_color_range,
tree_color_range = quantative_palette(),
node_label_color_range = quantative_palette(),
edge_label_color_range = quantative_palette(),
tree_label_color_range = quantative_palette(),
node_size_interval = range(node_size, na.rm = TRUE, finite = TRUE),
node_color_interval = NULL,
edge_size_interval = range(edge_size, na.rm = TRUE, finite = TRUE),
edge_color_interval = NULL,
node_label_max = 500,
edge_label_max = 500,
tree_label_max = 500,
overlap_avoidance = 1,
margin_size = c(0, 0, 0, 0),
layout = "reingold-tilford",
initial_layout = "fruchterman-reingold",
make_node_legend = TRUE,
make_edge_legend = TRUE,
title = NULL,
title_size = 0.08,
node_legend_title = "Nodes",
edge_legend_title = "Edges",
node_color_axis_label = NULL,
node_size_axis_label = NULL,
edge_color_axis_label = NULL,
edge_size_axis_label = NULL,
node_color_digits = 3,
node_size_digits = 3,
edge_color_digits = 3,
edge_size_digits = 3,
background_color = "#FFFFFF00",
output_file = NULL,
aspect_ratio = 1,
repel_labels = TRUE,
repel_force = 1,
repel_iter = 1000,
verbose = FALSE,
...
)
(other named arguments)
Passed to the igraph layout function used.
An object of type taxmap
The unique ids of taxa.
The unique id of supertaxon taxon_id is a part of.
See details on labels. Default: no labels.
See details on labels. Default: no labels.
See details on labels. The label to display above each graph. The value of the root of each graph will be used. Default: None.
See details on size. Default: constant size.
See details on size. Default: relative to node size.
See details on size. Default: relative to vertex size.
See details on size. Default: relative to edge size.
See details on size. Default: relative to graph size.
See details on colors. Default: grey.
See details on colors. Default: same as node color.
See details on colors. The value of the root of each graph will be used. Overwrites the node and edge color if specified. Default: Not used.
See details on colors. Default: black.
See details on colors. Default: black.
See details on colors. Default: black.
See details on transformations.
Default: "area".
See details on transformations.
Default: same as node_size_trans.
See details on transformations.
Default: same as node_size_trans.
See details on transformations.
Default: same as edge_size_trans.
See details on transformations.
Default: "area".
See details on transformations.
Default: "area".
See details on transformations. Default: same as node color transformation.
See details on transformations.
Default: "area".
See details on transformations.
Default: "area".
See details on transformations.
Default: "area".
See details on transformations.
Default: "area".
See details on ranges. Default: Optimize to balance overlaps and range size.
See details on ranges. Default: relative to node size range.
See details on ranges. Default: relative to node size.
See details on ranges. Default: relative to edge size.
See details on ranges. Default: relative to tree size.
See details on ranges. Default: Color-blind friendly palette.
See details on ranges. Default: same as node color.
See details on ranges. Default: Color-blind friendly palette.
See details on ranges. Default: Color-blind friendly palette.
See details on ranges. Default: Color-blind friendly palette.
See details on ranges. Default: Color-blind friendly palette.
See details on intervals.
Default: The range of values in node_size.
See details on intervals.
Default: The range of values in node_color.
See details on intervals.
Default: The range of values in edge_size.
See details on intervals.
Default: The range of values in edge_color.
The maximum number of node labels. Default: 20.
The maximum number of edge labels. Default: 20.
The maximum number of tree labels. Default: 20.
(numeric)
The relative importance of avoiding overlaps vs maximizing size range.
Higher numbers will cause node size optimization to avoid overlaps more.
Default: 1.
(numeric of length 2)
The horizontal and vertical margins. c(left, right, bottom, top).
Default: 0, 0, 0, 0.
The layout algorithm used to position nodes.
See details on layouts.
Default: "reingold-tilford".
he layout algorithm used to set the initial position
of nodes, passed as input to the layout algorithm.
See details on layouts.
Default: Not used.
if TRUE, make legend for node size/color mappings.
if TRUE, make legend for edge size/color mappings.
Name to print above the graph.
The size of the title relative to the rest of the graph.
The title of the legend for node data. Can be `NA` or `NULL` to remove the title.
The title of the legend for edge data. Can be `NA` or `NULL` to remove the title.
The label on the scale axis corresponding to node_color.
Default: The expression given to node_color.
The label on the scale axis corresponding to node_size.
Default: The expression given to node_size.
The label on the scale axis corresponding to edge_color.
Default: The expression given to edge_color.
The label on the scale axis corresponding to edge_size.
Default: The expression given to edge_size.
The number of significant figures used for the numbers on the scale axis corresponding to node_color.
Default: 3.
The number of significant figures used for the numbers on the scale axis corresponding to node_size.
Default: 3.
The number of significant figures used for the numbers on the scale axis corresponding to edge_color.
Default: 3.
The number of significant figures used for the numbers on the scale axis corresponding to edge_size.
Default: 3.
The background color of the plot. Default: Transparent
The path to one or more files to save the plot in using ggsave.
The type of the file will be determined by the extension given.
Default: Do not save plot.
The aspect_ratio of the plot.
If TRUE (Default), use the ggrepel package to spread out labels.
The force of which overlapping labels will be repelled from eachother.
The number of iterations used when repelling labels
If TRUE print progress reports as the function runs.
The labels of nodes, edges, and trees can be added. Node labels are centered over their node. Edge labels are displayed over edges, in the same orientation. Tree labels are displayed over their tree.
Accepts a vector, the same length taxon_id or a factor of its length.
The size of nodes, edges, labels, and trees can be mapped to various conditions. This is useful for displaying statistics for taxa, such as abundance. Only the relative size of the condition is used, not the values themselves. The <element>_size_trans (transformation) parameter can be used to make the size mapping non-linear. The <element>_size_range parameter can be used to proportionately change the size of an element based on the condition mapped to that element. The <element>_size_interval parameter can be used to change the limit at which a condition will be graphically represented as the same size as the minimum/maximum <element>_size_range.
Accepts a numeric vector, the same length taxon_id or a
factor of its length.
The colors of nodes, edges, labels, and trees can be mapped to various conditions. This is useful for visually highlighting/clustering groups of taxa. Only the relative size of the condition is used, not the values themselves. The <element>_color_trans (transformation) parameter can be used to make the color mapping non-linear. The <element>_color_range parameter can be used to proportionately change the color of an element based on the condition mapped to that element. The <element>_color_interval parameter can be used to change the limit at which a condition will be graphically represented as the same color as the minimum/maximum <element>_color_range.
Accepts a vector, the same length taxon_id or a factor of its length.
If a numeric vector is given, it is mapped to a color scale.
Hex values or color names can be used (e.g. #000000 or "black").
Mapping Properties
Before any conditions specified are mapped to an element property (color/size), they can be transformed to make the mapping non-linear. Any of the transformations listed below can be used by specifying their name. A customized function can also be supplied to do the transformation.
Proportional to radius/diameter of node
circular area; better perceptual accuracy than "linear"
Log base 10 of radius
Log base 2 of radius
Log base e of radius
Log base 10 of circular area
Log base 2 of circular area
Log base e of circular area
The displayed range of colors and sizes can be explicitly defined or automatically generated.
When explicitly used, the size range will proportionately increase/decrease the size of a particular element.
Size ranges are specified by supplying a numeric vector with two values: the minimum and maximum.
The units used should be between 0 and 1, representing the proportion of a dimension of the graph.
Since the dimensions of the graph are determined by layout, and not always square, the value
that 1 corresponds to is the square root of the graph area (i.e. the side of a square with
the same area as the plotted space).
Color ranges can be any number of color values as either HEX codes (e.g. #000000) or
color names (e.g. "black").
Layouts determine the position of node elements on the graph.
They are implemented using the igraph package.
Any additional arguments passed to heat_tree are passed to the igraph
function used.
The following character values are understood:
Use nicely. Let igraph choose the layout.
Use as_tree. A circular tree-like layout.
Use with_dh. A type of simulated annealing.
Use with_gem. A force-directed layout.
Use with_graphopt. A force-directed layout.
Use with_mds. Multidimensional scaling.
Use with_fr. A force-directed layout.
Use with_kk. A layout based on a physical model of springs.
Use with_lgl. Meant for larger graphs.
Use with_drl. A force-directed layout.
This is the minimum and maximum of values displayed on the legend scales.
Intervals are specified by supplying a numeric vector with two values: the minimum and maximum.
When explicitly used, the <element>_<property>_interval will redefine the way the actual conditional values are being represented
by setting a limit for the <element>_<property>.
Any condition below the minimum <element>_<property>_interval will be graphically represented the same as a condition AT the
minimum value in the full range of conditional values. Any value above the maximum <element>_<property>_interval will be graphically
represented the same as a value AT the maximum value in the full range of conditional values.
By default, the minimum and maximum equals the <element>_<property>_range used to infer the value of the <element>_<property>.
Setting a custom interval is useful for making <element>_<properties> in multiple graphs correspond to the same conditions,
or setting logical boundaries (such as c(0,1) for proportions.
Note that this is different from the <element>_<property>_range mapping property, which determines the size/color of graphed elements.
This package includes code from the R package ggrepel to handle label overlap avoidance with permission from the author of ggrepel Kamil Slowikowski. We included the code instead of depending on ggrepel because we are using internal functions to ggrepel that might change in the future. We thank Kamil Slowikowski for letting us use his code and would like to acknowledge his implementation of the label overlap avoidance used in metacoder.