Getting started • heattree

The package includes example data sets that are automatically loaded with the package (bansal_2021_tree), so you can try it out with minimal effort. After installing the packages, simply run the lines below to get an idea of how it works:

library(heattree)
heat_tree(bansal_2021_tree, metadata = bansal_2021_metadata, aesthetics = c(tipLabelColor = 'Lifestyle'))

You will have the option to interactively upload your own trees/metadata in the widgets menu as well.

Basic Usage

This package is designed to be as simple to use as possible while also allowing for advanced customization. In fact, since you can upload tree and metadata interactively, it is entirely valid to create a widget with no input:

library(heattree)
heat_tree()

You can also supply trees/metadata to plot when the widget in created. The following types of input data are currently supported:

Paths to newick files
Newick-formatted text (a character vector with a single item)
phylo objects from the ape package

For example, here is the test data included in the package in these three formats:

example_tree_path <- system.file('extdata', 'bansal_2021_tree.nwk', package = 'heattree')
example_text <- readLines(example_tree_path)
example_phylo <- ape::read.tree(example_tree_path)

These three commands all produce the same plot:

heat_tree(example_tree_path)
heat_tree(example_text)
heat_tree(example_phylo)

You can also supply metadata for the tree by supplying a path to a TSV/CSV or a data.frame/tibble.

This table must have a “node_id” column with values matching the IDs in the treefile. For example, this data is associated with the above example tree:

example_metadata_path <- system.file('extdata', 'bansal_2021_metadata.tsv', package = 'heattree')
example_metadata <- readr::read_tsv(example_metadata_path)
print(example_metadata)
#> # A tibble: 76 × 15
#>    Strain      `Genome size`   CDS `Genome status` `Source/Host` `Host taxonomy`
#>    <chr>               <dbl> <dbl> <chr>           <chr>         <chr>          
#>  1 Xanthomona…           4.9  3960 Draft           Sorghum vulg… Tracheophytes,…
#>  2 Xanthomona…           4.2  3385 Draft           Oryza sativa… Tracheophytes,…
#>  3 Xanthomona…           5.1  4416 Complete        Infected pep… Tracheophytes,…
#>  4 Xanthomona…           5    3937 Draft           Medicago sat… Tracheophytes,…
#>  5 Xanthomona…           5    4206 Draft           Leaves of So… Tracheophytes,…
#>  6 Xanthomona…           5    4175 Complete        Phaseolus vu… Tracheophytes,…
#>  7 Xanthomona…           5.1  4355 Draft           Citrus auran… Tracheophytes,…
#>  8 Xanthomona…           4.4  3263 Draft           Axonopus sco… Tracheophytes,…
#>  9 Xanthomona…           5.3  4208 Draft           Prunus persi… Tracheophytes,…
#> 10 Xanthomona…           4.9  3845 Draft           Bromus carin… Tracheophytes,…
#> # ℹ 66 more rows
#> # ℹ 9 more variables: Lifestyle <chr>, Location <chr>, `Isolation year` <dbl>,
#> #   `GC%` <dbl>, `# tRNA` <dbl>, Species <chr>, `Tree ID` <chr>,
#> #   Completeness <dbl>, Contamination <dbl>

Similar to tree input, both paths and parsed data are accepted. Metadata can be used to color or size tree elements, similar to how ggplot2 works. The aesthetics parameter is used to specify which columns correspond to which aesthetics. These two commands produce the same plot:

heat_tree(example_tree_path, metadata = example_metadata_path, aesthetics = c(tipLabelColor = 'Lifestyle'))
heat_tree(example_tree_path, metadata = example_metadata, aesthetics = c(tipLabelColor = 'Lifestyle'))

Check the heat-tree javascript package documentation for the list of valid aesthetics.

Initial settings

Although the widget is primarily designed for interactive use, the initial settings can be set programmatically. All of the value of options described in the heat-tree javascript package documentation can be used as optional parameters. For example, the layout can be changed to circular like so:

heat_tree(example_phylo)

Multiple trees

The heat_tree widget is capable of managing multiple trees at once. To initialize a widget with multiple trees, supply lists of tree and metadata inputs. If metadata/aesthetics are also supplied they must a list as well that corresponds to the list of trees. For example:

heat_tree(
  tree = list(tree_1, tree_2),
  metadata = list(metadata_1, metadata_2),
  aesthetics = list(NULL, c(tipLabelColor = 'Lifestyle')
)