export.figtree {SigTree}

Function to export a NEXUS file that can be opened in FigTree to produce a plot of the phylogenetic tree with branches colored according to significance of families of p-values

Description

export.figtree takes tree and unsorted.pvalues and produces a NEXUS file that can FigTree can subsequently open. The p-values for each branch (family of tips) are computed and the branches are colored accordingly. It computes the p-values based on arguments involving p-value adjustment (for multiple hypothesis testing) and either Stouffer's or Fisher's p-value combination method. There are arguments that allow for the customization of the p-value cutoff ranges as well as the colors to be used in the coloring of the branches. There is also an option to include annotations for each edge that contain the p-value for the corresponding branch.

Usage

export.figtree(tree, unsorted.pvalues, adjust=TRUE, side=1, 
	method="hommel", p.cutoffs=ifelse(rep(side==1, ifelse(side==1, 6, 3)),
	c(.01, .05, .1, .9, .95, .99), c(.01, .05, .1)), file="", 
	pal=ifelse(rep(side==1, ifelse(side==1, 1, length(p.cutoffs)+1)),
	"RdBu", rev(brewer.pal(length(p.cutoffs)+1,"Reds"))),
	test = "Stouffer", edge.label=TRUE, ignore.edge.length=FALSE,
	branch="edge")

Arguments

tree

a phylogenetic tree of class phylo.

unsorted.pvalues

a data frame (or matrix) with tip labels in column 1 and p-values in column 2. The tip labels must correspond to the tip labels in tree.

adjust

a logical argument that controls whether there is p-value adjustment performed (TRUE) or not (FALSE).

side

a numerical argument that takes values 1 and 2, depending on whether the p-values in unsorted.pvalues are 1-sided or 2-sided, respectively. Only used in p-value adjustment if adjust = TRUE.

method

one of the p-value adjustment methods (used for multiple-hypothesis testing) found in p.adjust.methods ("holm", "hochberg", "hommel", "BH", "bonferroni", "BY", "fdr", and "none"). See help for p.adjust for more details on these methods. method is only used if adjust = TRUE.

p.cutoffs

a vector of increasing p-value cutoffs (excluding 0 and 1) to determine the ranges of p-values used in the coloring of the branches.

file

the file path that the NEXUS file that FigTree can open is written to.

pal

one of the palettes from the RColorBrewer package (see brewer.pal.info for a list) or a vector of hexadecimal colors. These are the colors that are used to color the branches. The first color corresponds to the first range in p.cutoffs and so on.

test

a character string taking on "Hartung", "Stouffer", or "Fisher". This is the p-value combination method that will be used. In most cases, "Stouffer" will be most appropriate, unless adonis.tree indicates significant evidence of dependence among p-values, in which case "Hartung" is preferred.

edge.label

a logical argument that, when TRUE, produces edge label annotations in FigTree. These annotations are the p-values of the edge's parent node when branch="node". They are accessible via highlighting an edge, hitting the Annotate button, and selecting P-value.

ignore.edge.length

a logical parameter. When TRUE, the edge lengths from tree are ignored and FigTree creates its own edge lengths. ignore.edge.length has no effect if the edges in tree have no defined length.

branch

a character controlling branch definition: "edge" and "node" are the only options. This does not affect statistical methods, only the colors used in edge coloring. Prior to package version 1.2, only branch="node" was implemented.

Details

The tip labels of tree (accessed via tree$tip.label) must have the same names (and the same length) as the tip labels in unsorted.pvalues, but may be in a different order. The p-values in column 2 of unsorted.pvalues obviously must be in the [0, 1] range. p.cutoffs takes values in the (0, 1) range. The default value for p.cutoffs is c(0.01, 0.05, 0.1, 0.9, 0.95, 0.99) if side is 1 and c(0.01, 0.05, 0.1) if side is 2. Thus, the ranges (when side is 1) are: [0, .01], (.01, .05], ..., (.99, 1]. These ranges correspond to the colors specified in pal. P-values in the [0, .01] range correspond to the left-most color if pal is a palette (view this via display.brewer.pal(x, pal) - where x is the number of colors to be used) or the first value in the vector if pal is a vector of colors. If pal is a vector of colors, then the length of pal should be one greater than the length of p.cutoffs. In other words, its length must be the same as the number of p-value ranges. In addition, each color in this vector of colors needs to be in hexadecimal format, for example, "#B2182B". Formats of colors other than hexadecimal will likely give unwanted results in the edges of the tree produced in FigTree, such as all-black edges or the edges being colored in a meaningless way. This is because the color conversion assumes hexadecimal colors. The default value of pal is "RdBu" (a divergent palette of reds and blues, with reds corresponding to small p-values) if side is 1 and the reverse of "Reds" (a sequential palette) if side is 2. The sequential palettes in RColorBrewer go from light to dark, so "Reds" is reversed so that the dark red corresponds to small p-values. It probably makes more sense to use a divergent palette when using 1-sided p-values and a sequential palette (reversed) when using 2-sided p-values. To create a vector of reversed colors from a palette with x number of colors and "PaletteName" as the name of the palette, use rev(brewer.pal(x, "PaletteName")). ignore.edge.length may be useful to get a more uniformly-shaped tree. export.figtree assumes that each internal node has exactly two descendants. It also assumes that each internal node has a lower number than each of its ancestors (excluding tips).

The branch argument controls whether edge coloring corresponds to the combined p-value of the tips below the edge ("edge") or of the tips below the edge's leading (away from the tips) node ("node"). Note that if branch="node" is used, then both edges leaving a node will necessarily be colored the same.

To access the tutorial document for this package (including this function), type in R: vignette("SigTree")

Value

This function creates a NEXUS file that can be opened by the program FigTree.

Author(s)

John R. Stevens and Todd R. Jones

References

Stevens J.R., Jones T.R., Lefevre M., Ganesan B., and Weimer B.C. (2017) "SigTree: A Microbial Community Analysis Tool to Identify and Visualize Significantly Responsive Branches in a Phylogenetic Tree." Computational and Structural Biotechnology Journal 15:372-378.

Jones T.R. (2012) "SigTree: An Automated Meta-Analytic Approach to Find Significant Branches in a Phylogenetic Tree" (2012). MS Thesis, Utah State University, Department of Mathematics and Statistics. http://digitalcommons.usu.edu/etd/1314

FigTree is available at http://tree.bio.ed.ac.uk/software/figtree/.

Examples

### To access the tutorial document for this package, type in R (not run here): 
# vignette("SigTree")

### Create tree, then data frame, then use plotSigTree to plot the tree
### Code for random tree and data frame
node.size <- 10
seed <- 109
# Create tree
set.seed(seed)
library(ape)
r.tree <- rtree(node.size)
# Create p-values data frame
set.seed(seed)
r.pval <- rbeta(node.size, .1, .1)
# Randomize the order of the tip labels
# (just to emphasize that labels need not be sorted)
set.seed(seed)
r.tip.label <- sample(r.tree$tip.label, size=length(r.tree$tip.label))
r.pvalues <- data.frame(label=r.tip.label, pval=r.pval)

# Check for dependence among p-values; lack of significance here
# indicates default test="Stouffer" is appropriate; 
# otherwise, test="Hartung" would be more appropriate.
adonis.tree(r.tree,r.pvalues)

# Export "ExportFigtree1.tre" file that can be opened in FigTree
library(phyext2)
export.figtree(r.tree, r.pvalues, test="Stouffer", file="ExportFigtree1.tre")