diff --git a/R/ordination-methods.R b/R/ordination-methods.R index 9f51fec7..b70a0cf7 100644 --- a/R/ordination-methods.R +++ b/R/ordination-methods.R @@ -247,12 +247,13 @@ ordinate = function(physeq, method="DCA", distance="bray", formula=NULL, ...){ #' to perform a #' Double Principle Coordinate Analysis (DPCoA), relying heavily on #' the underlying (and more general) function, \code{\link[ade4]{dpcoa}}. -#' The distance object ultimately provided as the cophenetic/patristic -#' (\code{\link[ape]{cophenetic.phylo}}) distance between the species. -#' -#' In most real-life, real-data applications, the phylogenetic tree -#' will not provide a Euclidean distance matrix, and so a correction -#' will be performed, if needed. See \code{correction} argument. +#' The distance object ultimately provided is the square root of the +#' cophenetic/patristic (\code{\link[ape]{cophenetic.phylo}}) distance +#' between the species, which is always Euclidean. +#' +#' Although this distance is Euclidean, for numerical reasons it +#' will sometimes look non-Euclidean, and a correction will be performed. +#' See \code{correction} argument. #' #' @param physeq (Required). A \code{\link{phyloseq-class}} object #' containing, at a minimum, abundance (\code{\link{otu_table-class}}) and @@ -265,14 +266,14 @@ ordinate = function(physeq, method="DCA", distance="bray", formula=NULL, ...){ #' and return a new \code{dist}ance object that is Euclidean. #' If testing a distance object, try \code{\link[ade4]{is.euclid}}. #' -#' In most real-life, real-data applications, the phylogenetic tree -#' will not provide a Euclidean distance matrix, and so a correction -#' will be needed. -#' Two recommended correction methods are +#' +#' Although the distance matrix should always be Euclidean, for numerical +#' reasons it will sometimes appear non-Euclidean and a correction method must +#' be applied. Two recommended correction methods are #' \code{\link[ade4]{cailliez}} and \code{\link[ade4]{lingoes}}. #' The default is \code{cailliez}, -#' but not for any particularly special reason. If the patristic -#' distance matrix turns out to be Euclidian, no correction will be +#' but not for any particularly special reason. If the +#' distance matrix is Euclidian, no correction will be #' performed, regardless of the value of the \code{correction} argument. #' #' @param scannf (Optional). Logical. Default is \code{FALSE}. This @@ -335,7 +336,7 @@ DPCoA <- function(physeq, correction=cailliez, scannf=FALSE, ...){ if(taxa_are_rows(OTU) ){ OTU <- t(OTU) } # get the patristic distances between the species from the tree - patristicDist <- as.dist(cophenetic.phylo(tree)) + patristicDist <- sqrt(as.dist(cophenetic.phylo(tree))) # if the patristic distances are not Euclidean, # then correct them or throw meaningful error. @@ -638,4 +639,4 @@ function(physeq, formula, distance, ...){ return(capscale.phyloseq(physeq, formula, distance, ...)) } }) -################################################################################ \ No newline at end of file +################################################################################