add warning message to force.ultrametric

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: phytools
-Version: 0.7-85
-Date: 2021-8-04
+Version: 0.7-86
+Date: 2021-8-10
 Title: Phylogenetic Tools for Comparative Biology (and Other Things)
 Author: Liam J. Revell
 Maintainer: Liam J. Revell <liam.revell@umb.edu>

R/utilities.R

@@ -355,9 +355,20 @@ linklabels<-function(text,tips,link.type=c("bent","curved","straight"),
 }
 
 ## function forces a tree to be ultrametric using two different methods
-## written by Liam J. Revell 2017
+## written by Liam J. Revell 2017, 2021
 
-force.ultrametric<-function(tree,method=c("nnls","extend")){
+force.ultrametric<-function(tree,method=c("nnls","extend"),...){
+	if(hasArg(message)) message<-list(...)$message
+	else message<-TRUE
+	if(message){
+		cat("***************************************************************\n")
+		cat("*                          Note:                              *\n")
+		cat("*    force.ultrametric does not include a formal method to    *\n")
+		cat("*  ultrametricize a tree & should only be used to coerce to   *\n")
+		cat("*   a phylogeny that fails is.ultramtric due to rounding --   *\n")
+		cat("*   not as a substitute for formal rate-smoothing methods.    *\n")
+		cat("***************************************************************\n")
+	}
 	method<-method[1]
 	if(method=="nnls") tree<-nnls.tree(cophenetic(tree),tree,
 		rooted=TRUE,trace=0)

man/force.ultrametric.Rd

@@ -2,11 +2,12 @@
 \alias{force.ultrametric}
 \title{Forces a phylogenetic tree to be ultrametric}
 \usage{
-force.ultrametric(tree, method=c("nnls","extend"))
+force.ultrametric(tree, method=c("nnls","extend"), ...)
 }
 \arguments{
 	\item{tree}{an object of class \code{"phylo"}.}
 	\item{method}{the method to use to force the tree to be ultrametric. Options are \code{"nnls"} (which uses the phangorn function \code{\link{nnls.tree}} internally), or \code{"extend"}.}
+	\item{...}{optional arguments.}
 }
 \description{
 	This function forces an object of class \code{"phylo"} to be ultrametric. This is achieved either by using \code{\link{nnls.tree}} from the phangorn package to compute the set of edge lengths that result in a minimized sum-of-squares distance between the patristic distance of the output and input trees (\code{method="nnls"}); or by simply extending all the external edges of the tree to match the external edge with the greatest total height (\code{method="extend"}).