man/phymltest.Rd

   1 \name{phymltest}
   2 \alias{phymltest}
   3 \alias{print.phymltest}
   4 \alias{summary.phymltest}
   5 \alias{plot.phymltest}
   6 \title{Fits a Bunch of Models with PhyML}
   7 \usage{
   8 phymltest(seqfile, format = "interleaved", itree = NULL,
   9           exclude = NULL, execname = NULL, append = TRUE)
  10 \method{print}{phymltest}(x, ...)
  11 \method{summary}{phymltest}(object, ...)
  12 \method{plot}{phymltest}(x, main = NULL, col = "blue", ...)
  13 }
  14 \arguments{
  15   \item{seqfile}{a character string giving the name of the file that
  16     contains the DNA sequences to be analysed by PhyML.}
  17   \item{format}{a character string specifying the format of the DNA
  18     sequences: either \code{"interleaved"} (the default), or
  19     \code{"sequential"}.}
  20   \item{itree}{a character string giving the name of a file with a tree
  21     in Newick format to be used as an initial tree by PhyML. If
  22     \code{NULL} (the default), PhyML uses a ``BIONJ'' tree.}
  23   \item{exclude}{a vector of mode character giving the models to be
  24     excluded from the analysis. These must be among those below, and
  25     follow the same syntax.}
  26   \item{execname}{a character string specifying the name of the PhyML
  27     executable. This argument can be left as \code{NULL} if PhyML's
  28     default names are used: \code{"phyml_3.0_linux32"},
  29     \code{"phyml_3.0_macintel"}, or \code{"phyml_3.0_win32.exe"}, under
  30     Linux, MacOS, or Windows respectively.}
  31   \item{append}{a logical indicating whether to erase previous PhyML
  32     output files if present; the default is to not erase.}
  33   \item{x}{an object of class \code{"phymltest"}.}
  34   \item{object}{an object of class \code{"phymltest"}.}
  35   \item{main}{a title for the plot; if left \code{NULL}, a title is made
  36     with the name of the object (use \code{main = ""} to have no
  37     title).}
  38   \item{col}{a colour used for the segments showing the AIC values (blue
  39     by default).}
  40   \item{\dots}{further arguments passed to or from other methods.}
  41 }
  42 \description{
  43   This function calls PhyML and fits successively 28 models of DNA
  44   evolution. The results are saved on disk, as PhyML usually does, and
  45   returned in R as a vector with the log-likelihood value of each model.
  46 }
  47 \details{
  48   The present function requires version 3.0.1 of PhyML; it won't work with
  49   older versions.
  50
  51   The user must take care to set correctly the three different paths
  52   involved here: the path to PhyML's binary, the path to the sequence
  53   file, and the path to R's working directory. The function should work
  54   if all three paths are different. Obviously, there should be no problem
  55   if they are all the same.
  56
  57   The following syntax is used for the models:
  58
  59   "X[Y][Z]00[+I][+G]"
  60
  61   where "X" is the first letter of the author of the model, "Y" and "Z"
  62   are possibly other co-authors of the model, "00" is the year of the
  63   publication of the model, and "+I" and "+G" indicates whether the
  64   presence of invariant sites and/or a gamma distribution of
  65   substitution rates have been specified. Thus, Kimura's model is
  66   denoted "K80" and not "K2P". The exception to this rule is the general
  67   time-reversible model which is simple denoted "GTR" model.
  68
  69   The seven substitution models used are: "JC69", "K80", "F81", "F84",
  70   "HKY85", "TN93", and "GTR". These models are then altered by adding
  71   the "+I" and/or "+G", resulting thus in four variants for each of them
  72   (e.g., "JC69", "JC69+I", "JC69+G", "JC69+I+G"). Some of these models
  73   are described in the help page of \code{\link{dist.dna}}.
  74
  75   When a gamma distribution of substitution rates is specified, four
  76   categories are used (which is PhyML's default behaviour), and the
  77   ``alpha'' parameter is estimated from the data.
  78
  79   For the models with a different substition rate for transitions and
  80   transversions, these rates are left free and estimated from the data
  81   (and not constrained with a ratio of 4 as in PhyML's default).
  82
  83   The option \code{path2exec} has been removed in the present version:
  84   the path to PhyML's executable can be specified with the option
  85   \code{execname}.
  86 }
  87 \note{
  88   It is important to note that the models fitted by this function is
  89   only a small fraction of the models possible with PhyML. For instance,
  90   it is possible to vary the number of categories in the (discretized)
  91   gamma distribution of substitution rates, and many parameters can be
  92   fixed by the user. The results from the present function should rather
  93   be taken as indicative of a best model.
  94 }
  95 \value{
  96   \code{phymltest} returns an object of class \code{"phymltest"}: a
  97   numeric vector with the models as names.
  98
  99   The \code{print} method prints an object of class \code{"phymltest"}
 100   as matrix with the name of the models, the number of free parameters,
 101   the log-likelihood value, and the value of the Akaike information
 102   criterion (AIC = -2 * loglik + 2 * number of free parameters)
 103
 104   The \code{summary} method prints all the possible likelihood ratio
 105   tests for an object of class \code{"phymltest"}.
 106
 107   The \code{plot} method plots the values of AIC of an object of class
 108   \code{"phymltest"} on a vertical scale.
 109 }
 110 \references{
 111   Posada, D. and Crandall, K. A. (2001) Selecting the best-fit model of
 112   nucleotide substitution. \emph{Systematic Biology}, \bold{50},
 113   580--601.
 114
 115   Guindon, S. and Gascuel, O. (2003) A simple, fast, and accurate
 116   algorithm to estimate large phylogenies by maximum likelihood.
 117   \emph{Systematic Biology}, \bold{52}, 696--704.
 118   \url{http://www.atgc-montpellier.fr/phyml/}
 119 }
 120 \author{Emmanuel Paradis}
 121 \seealso{
 122   \code{\link{read.tree}}, \code{\link{write.tree}},
 123   \code{\link{dist.dna}}
 124 }
 125 \examples{
 126 ### A `fake' example with random likelihood values: it does not
 127 ### make sense, but does not need PhyML and gives you a flavour
 128 ### of what the output looks like:
 129 x <- runif(28, -100, -50)
 130 names(x) <- .phymltest.model
 131 class(x) <- "phymltest"
 132 x
 133 summary(x)
 134 plot(x)
 135 plot(x, main = "", col = "red")
 136 ### This example needs PhyML, copy/paste or type the
 137 ### following commands if you want to try them, eventually
 138 ### changing setwd() and the options of phymltest()
 139 \dontrun{
 140 setwd("D:/phyml_v2.4/exe") # under Windows
 141 data(woodmouse)
 142 write.dna(woodmouse, "woodmouse.txt")
 143 X <- phymltest("woodmouse.txt")
 144 X
 145 summary(X)
 146 plot(X)
 147 }
 148 }
 149 \keyword{models}