export.inherit {SigTree}

Function to produce a CSV file with the p-value for each branch as well as a list of all of the tips in each branch's family

Description

export.inherit takes tree and unsorted.pvalues and produces a CSV file (or data frame) with p-values for each branch (including tips) as well as a list of all of the tips that belong to each branch's family (i.e., all of the tips that are descendants of the branch). The p-values are computed based on arguments involving p-value adjustment (for multiple hypothesis testing) and either Stouffer's or Fisher's p-value combination method.

Usage

export.inherit(tree, unsorted.pvalues, adjust = TRUE, side = 1, method = "hommel",
file = "", test = "Stouffer", frame = 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.

file

the file path for the CSV file to be written to. If frame=TRUE, no CSV file is created. If frame=FALSE, a CSV file will only be created if file is specified.

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.

frame

a logical argument that controls whether or not to return (in R) the resulting data.frame object. If FALSE, file must be specified.

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. The edge and node numbering is internal to class phylo, and are not necessarily sequential numbers.

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. export.inherit 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).

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

Value

This function produces a CSV file; alternatively, if frame=TRUE, this function will return a data.frame object.

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

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)

# Create CSV file called "ExportInherit1.csv"
export.inherit(r.tree, r.pvalues, test="Stouffers", file="ExportInherit1.csv")

# Look at resulting file in R -- see package vignette
f <- export.inherit(r.tree, r.pvalues, test="Stouffers", frame=TRUE)
f