man/dist.dna.Rd

   1 \name{dist.dna}
   2 \alias{dist.dna}
   3 \title{Pairwise Distances from DNA Sequences}
   4 \usage{
   5 dist.dna(x, model = "K80", variance = FALSE,
   6          gamma = FALSE, pairwise.deletion = FALSE,
   7          base.freq = NULL, as.matrix = FALSE)
   8 }
   9 \arguments{
  10   \item{x}{a matrix or a list containing the DNA sequences; this must be
  11     of class \code{"DNAbin"} (use \code{\link{as.DNAbin}} is they are
  12     stored as character).}
  13   \item{model}{a character string specifying the evlutionary model to be
  14     used; must be one of \code{"raw"}, \code{"N"}, \code{"TS"},
  15     \code{"TV"}, \code{"JC69"}, \code{"K80"} (the default),
  16     \code{"F81"}, \code{"K81"}, \code{"F84"}, \code{"BH87"},
  17     \code{"T92"}, \code{"TN93"}, \code{"GG95"}, \code{"logdet"},
  18     \code{"paralin"}, \code{"indel"}, or \code{"indelblock"}.}
  19   \item{variance}{a logical indicating whether to compute the variances
  20     of the distances; defaults to \code{FALSE} so the variances are not
  21     computed.}
  22   \item{gamma}{a value for the gamma parameter which is possibly used to
  23     apply a gamma correction to the distances (by default \code{gamma =
  24       FALSE} so no correction is applied).}
  25   \item{pairwise.deletion}{a logical indicating whether to delete the
  26     sites with missing data in a pairwise way. The default is to delete
  27     the sites with at least one missing data for all sequences (ignored
  28     if \code{model = "indel"} or \code{"indelblock"}).}
  29   \item{base.freq}{the base frequencies to be used in the computations
  30     (if applicable, i.e. if \code{method = "F84"}). By default, the
  31     base frequencies are computed from the whole sample of sequences.}
  32   \item{as.matrix}{a logical indicating whether to return the results as
  33     a matrix. The default is to return an object of class
  34     \link[stats]{dist}.}
  35 }
  36 \description{
  37   This function computes a matrix of pairwise distances from DNA
  38   sequences using a model of DNA evolution. Eleven substitution models
  39   (and the raw distance) are currently available.
  40 }
  41 \details{
  42   The molecular evolutionary models available through the option
  43   \code{model} have been extensively described in the literature. A
  44   brief description is given below; more details can be found in the
  45   References.
  46
  47 \itemize{
  48   \item{\code{raw}, \code{N}: }{This is simply the proportion or the number of
  49     sites that differ between each pair of sequences. This may be useful
  50     to draw ``saturation plots''. The options \code{variance} and
  51     \code{gamma} have no effect, but \code{pairwise.deletion} can.}
  52
  53   \item{\code{TS}, \code{TV}: }{These are the numbers of transitions and
  54     transversions, respectively.}
  55
  56   \item{\code{JC69}: }{This model was developed by Jukes and Cantor (1969). It
  57     assumes that all substitutions (i.e. a change of a base by another
  58     one) have the same probability. This probability is the same for all
  59     sites along the DNA sequence. This last assumption can be relaxed by
  60     assuming that the substition rate varies among site following a
  61     gamma distribution which parameter must be given by the user. By
  62     default, no gamma correction is applied. Another assumption is that
  63     the base frequencies are balanced and thus equal to 0.25.}
  64
  65   \item{\code{K80}: }{The distance derived by Kimura (1980), sometimes referred
  66     to as ``Kimura's 2-parameters distance'', has the same underlying
  67     assumptions than the Jukes--Cantor distance except that two kinds of
  68     substitutions are considered: transitions (A <-> G, C <-> T), and
  69     transversions (A <-> C, A <-> T, C <-> G, G <-> T). They are assumed
  70     to have different probabilities. A transition is the substitution of
  71     a purine (C, T) by another one, or the substitution of a pyrimidine
  72     (A, G) by another one. A transversion is the substitution of a
  73     purine by a pyrimidine, or vice-versa. Both transition and
  74     transversion rates are the same for all sites along the DNA
  75     sequence. Jin and Nei (1990) modified the Kimura model to allow for
  76     variation among sites following a gamma distribution. Like for the
  77     Jukes--Cantor model, the gamma parameter must be given by the
  78     user. By default, no gamma correction is applied.}
  79
  80   \item{\code{F81}: }{Felsenstein (1981) generalized the Jukes--Cantor model
  81     by relaxing the assumption of equal base frequencies. The formulae
  82     used in this function were taken from McGuire et al. (1999)}.
  83
  84   \item{\code{K81}: }{Kimura (1981) generalized his model (Kimura 1980) by
  85     assuming different rates for two kinds of transversions: A <-> C and
  86     G <-> T on one side, and A <-> T and C <-> G on the other. This is
  87     what Kimura called his ``three substitution types model'' (3ST), and
  88     is sometimes referred to as ``Kimura's 3-parameters distance''}.
  89
  90   \item{\code{F84}: }{This model generalizes K80 by relaxing the assumption
  91     of equal base frequencies. It was first introduced by Felsenstein in
  92     1984 in Phylip, and is fully described by Felsenstein and Churchill
  93     (1996). The formulae used in this function were taken from McGuire
  94     et al. (1999)}.
  95
  96   \item{\code{BH87}: }{Barry and Hartigan (1987) developed a distance based
  97     on the observed proportions of changes among the four bases. This
  98     distance is not symmetric.}
  99
 100   \item{\code{T92}: }{Tamura (1992) generalized the Kimura model by relaxing
 101     the assumption of equal base frequencies. This is done by taking
 102     into account the bias in G+C content in the sequences. The
 103     substitution rates are assumed to be the same for all sites along
 104     the DNA sequence.}
 105
 106   \item{\code{TN93}: }{Tamura and Nei (1993) developed a model which assumes
 107     distinct rates for both kinds of transition (A <-> G versus C <->
 108     T), and transversions. The base frequencies are not assumed to be
 109     equal and are estimated from the data. A gamma correction of the
 110     inter-site variation in substitution rates is possible.}
 111
 112   \item{\code{GG95}: }{Galtier and Gouy (1995) introduced a model where the
 113     G+C content may change through time. Different rates are assumed for
 114     transitons and transversions.}
 115
 116   \item{\code{logdet}: }{The Log-Det distance, developed by Lockhart et
 117     al. (1994), is related to BH87. However, this distance is
 118     symmetric. Formulae from Gu and Li (1996) are used.
 119     \code{dist.logdet} in \pkg{phangorn} uses a different
 120     implementation that gives substantially different distances for
 121     low-diverging sequences.}
 122
 123   \item{\code{paralin}: }{Lake (1994) developed the paralinear distance which
 124     can be viewed as another variant of the Barry--Hartigan distance.}
 125
 126   \item{\code{indel}: }{this counts the number of sites where there an
 127     insertion/deletion gap in one sequence and not in the other.}
 128
 129   \item{\code{indelblock}: }{same than before but contiguous gaps are
 130     counted as a single unit. Note that the distance between `-A-' and
 131     `A--' is 3 because there are three different blocks of gaps, whereas
 132     the ``indel'' distance will be 2.}
 133 }}
 134 \value{
 135   an object of class \link[stats]{dist} (by default), or a numeric
 136   matrix if \code{as.matrix = TRUE}. If \code{model = "BH87"}, a numeric
 137   matrix is returned because the Barry--Hartigan distance is not
 138   symmetric.
 139
 140   If \code{variance = TRUE} an attribute called \code{"variance"} is
 141   given to the returned object.
 142 }
 143 \references{
 144   Barry, D. and Hartigan, J. A. (1987) Asynchronous distance between
 145   homologous DNA sequences. \emph{Biometrics}, \bold{43}, 261--276.
 146
 147   Felsenstein, J. (1981) Evolutionary trees from DNA sequences: a
 148   maximum likelihood approach. \emph{Journal of Molecular Evolution},
 149   \bold{17}, 368--376.
 150
 151   Felsenstein, J. and Churchill, G. A. (1996) A Hidden Markov model
 152   approach to variation among sites in rate of evolution.
 153   \emph{Molecular Biology and Evolution}, \bold{13}, 93--104.
 154
 155   Galtier, N. and Gouy, M. (1995) Inferring phylogenies from DNA
 156   sequences of unequal base compositions. \emph{Proceedings of the
 157     National Academy of Sciences USA}, \bold{92}, 11317--11321.
 158
 159   Gu, X. and Li, W.-H. (1996) Bias-corrected paralinear and LogDet
 160   distances and tests of molecular clocks and phylogenies under
 161   nonstationary nucleotide frequencies. \emph{Molecular Biology and
 162     Evolution}, \bold{13}, 1375--1383.
 163
 164   Jukes, T. H. and Cantor, C. R. (1969) Evolution of protein
 165   molecules. in \emph{Mammalian Protein Metabolism}, ed. Munro, H. N.,
 166   pp. 21--132, New York: Academic Press.
 167
 168   Kimura, M. (1980) A simple method for estimating evolutionary rates of
 169   base substitutions through comparative studies of nucleotide
 170   sequences. \emph{Journal of Molecular Evolution}, \bold{16}, 111--120.
 171
 172   Kimura, M. (1981) Estimation of evolutionary distances between
 173   homologous nucleotide sequences. \emph{Proceedings of the National
 174     Academy of Sciences USA}, \bold{78}, 454--458.
 175
 176   Jin, L. and Nei, M. (1990) Limitations of the evolutionary parsimony
 177   method of phylogenetic analysis. \emph{Molecular Biology and
 178     Evolution}, \bold{7}, 82--102.
 179
 180   Lake, J. A. (1994) Reconstructing evolutionary trees from DNA and
 181   protein sequences: paralinear distances. \emph{Proceedings of the
 182     National Academy of Sciences USA}, \bold{91}, 1455--1459.
 183
 184   Lockhart, P. J., Steel, M. A., Hendy, M. D. and Penny, D. (1994)
 185   Recovering evolutionary trees under a more realistic model of sequence
 186   evolution. \emph{Molecular Biology and Evolution}, \bold{11},
 187   605--602.
 188
 189   McGuire, G., Prentice, M. J. and Wright, F. (1999). Improved error
 190   bounds for genetic distances from DNA sequences. \emph{Biometrics},
 191   \bold{55}, 1064--1070.
 192
 193   Tamura, K. (1992) Estimation of the number of nucleotide substitutions
 194   when there are strong transition-transversion and G + C-content
 195   biases. \emph{Molecular Biology and Evolution}, \bold{9}, 678--687.
 196
 197   Tamura, K. and Nei, M. (1993) Estimation of the number of nucleotide
 198   substitutions in the control region of mitochondrial DNA in humans and
 199   chimpanzees. \emph{Molecular Biology and Evolution}, \bold{10}, 512--526.
 200 }
 201 \author{Emmanuel Paradis}
 202 \seealso{
 203   \code{\link{read.GenBank}}, \code{\link{read.dna}},
 204   \code{\link{write.dna}},  \code{\link{DNAbin}},
 205   \code{\link{dist.gene}}, \code{\link{cophenetic.phylo}},
 206   \code{\link[stats]{dist}}
 207 }
 208 \keyword{manip}
 209 \keyword{multivariate}