Skip to contents

Combine metadata (a line list) with a phylogenetic tree

Source: R/phylepic.R
phylepic.Rd

Some checks are performed to catch issues where the metadata and tree tips don't match up. Any columns in metadata that are factors have all levels that do not appear in the data dropped.

Usage

phylepic(
  tree,
  metadata,
  name,
  date,
  unmatched_tips = c("error", "drop", "keep")
)

Arguments

tree

An object convertible to a tbl_graph. This will usually be a "phylo" object, but see tidygraph::tbl_graph for more details.

metadata

A data frame.

name

Column in metadata that corresponds to the tree's tip labels (tidy-eval).

date

Column in metadata that contains the date data (class "Date") for the tips (tidy-eval).

unmatched_tips

Action to take when tree contains tip labels that do not appear in name. "error" aborts with an error message, "drop" drops unmatched tips from tree, "keep".

Value

An object of class "phylepic".

Details

To reduce surprises when matching metadata and tree, by default an error occurs when there are tree tips that do not have associated metadata. On the other hand, it it expected that metadata might contain rows that do not correspond to the tips in tree.

This often means that factor columns from metadata will contain levels that do not appear at all in the tree. For plotting, ggplot2::discrete_scale normally solves this with drop = TRUE, however this can lead to inconsistencies when sharing the same scale across multiple phylepic panels. phylepic() drops unused levels in all factors so that scales can use drop = FALSE for consistency.

Examples

library(ape)

tree <- read.tree(system.file("enteric.newick", package = "phylepic"))
metadata <- read.csv(
  system.file("enteric_metadata.csv", package = "phylepic")
)
phylepic(tree, metadata, name, as.Date(collection_date))
#> Dated phylogenetic tree with 50 tips, and their associated metadata.
#> 
#> Tip labels: "NSW-0356" "NSW-0333" "NSW-0054" "NSW-0287" "NSW-0095" ...
#> 
#> Date values: as.Date(collection_date)
#> 
#> Metadata 'data.frame':	50 obs. of  4 variables:
#>  $ name           : chr  "NSW-0004" "NSW-0020" "NSW-0029" "NSW-0042" ...
#>  $ collection_date: chr  "2013-02-18" "2016-11-19" "2017-01-13" "2017-02-28" ...
#>  $ source         : chr  NA NA NA NA ...
#>  $ cluster        : chr  NA NA NA NA ...