X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=man%2Fread.dna.Rd;h=2863ad85c32ec8c47efeca1fa852bf57a5a14315;hb=2014b83971be4b9cd1644d6127837df798e9335c;hp=71473d6a98eb53b5e06379cb86862114d67f351f;hpb=c827059eeafc8cbe41c812b26979543ab287803e;p=ape.git

diff --git a/man/read.dna.Rd b/man/read.dna.Rd
index 71473d6..2863ad8 100644
--- a/man/read.dna.Rd
+++ b/man/read.dna.Rd
@@ -3,26 +3,30 @@
 \title{Read DNA Sequences in a File}
 \usage{
 read.dna(file, format = "interleaved", skip = 0,
-         nlines = 0, comment.char = "#", seq.names = NULL,
-         as.character = FALSE)
+         nlines = 0, comment.char = "#",
+         as.character = FALSE, as.matrix = NULL)
 }
 \arguments{
   \item{file}{a file name specified by either a variable of mode character,
     or a double-quoted string.}
   \item{format}{a character string specifying the format of the DNA
-    sequences. Three choices are possible: \code{"interleaved"},
-    \code{"sequential"}, or \code{"fasta"}, or any unambiguous
-    abbreviation of these.}
+    sequences. Four choices are possible: \code{"interleaved"},
+    \code{"sequential"}, \code{"clustal"}, or \code{"fasta"}, or any
+    unambiguous abbreviation of these.}
   \item{skip}{the number of lines of the input file to skip before
     beginning to read data.}
   \item{nlines}{the number of lines to be read (by default the file is
     read untill its end).}
   \item{comment.char}{a single character, the remaining of the line
     after this character is ignored.}
-  \item{seq.names}{the names to give to each sequence; by default the
-    names read in the file are used.}
   \item{as.character}{a logical controlling whether to return the
     sequences as an object of class \code{"DNAbin"} (the default).}
+  \item{as.matrix}{(used if \code{format = "fasta"}) one of the three
+    followings: (i) \code{NULL}: returns the sequences in a matrix if
+    they are of the same length, otherwise in a list; (ii) \code{TRUE}:
+    returns the sequences in a matrix, or stops with an error if they
+    are of different lengths; (iii) \code{FALSE}: always returns the
+    sequences in a list.}
 }
 \description{
   This function reads DNA sequences in a file, and returns a matrix or a
@@ -34,8 +38,7 @@ read.dna(file, format = "interleaved", skip = 0,
 \details{
   This function follows the interleaved and sequential formats defined
   in PHYLIP (Felsenstein, 1993) but with the original feature than there
-  is no restriction on the lengths of the taxa names (though a data file
-  with 10-characters-long taxa names is fine as well). For these two
+  is no restriction on the lengths of the taxa names. For these two
   formats, the first line of the file must contain the dimensions of the
   data (the numbers of taxa and the numbers of nucleotides); the
   sequences are considered as aligned and thus must be of the same
@@ -45,31 +48,33 @@ read.dna(file, format = "interleaved", skip = 0,
   way with blanks and line-breaks inside (with the restriction that the
   first ten nucleotides must be contiguous for the interleaved and
   sequential formats, see below). The names of the sequences are read in
-  the file unless the `seq.names' option is used. Particularities for
-  each format are detailed below.
+  the file. Particularities for each format are detailed below.
 
-  \item{Interleaved:}{the function starts to read the sequences when it
-    finds 10 contiguous characters belonging to the ambiguity code of
-    the IUPAC (namely A, C, G, T, U, M, R, W, S, Y, K, V, H, D, B, and
-    N, upper- or lowercase, so you might run into trouble if you have a
-    taxa name with 10 contiguous letters among these!) All characters
-    before the sequences are taken as the taxa names after removing the
-    leading and trailing spaces (so spaces in a taxa name are
-    allowed). It is assumed that the taxa names are not repeated in the
-    subsequent blocks of nucleotides.}
+\itemize{
+  \item{Interleaved:}{the function starts to read the sequences after it
+    finds one or more spaces (or tabulations). All characters before the
+    sequences are taken as the taxa names after removing the leading and
+    trailing spaces (so spaces in taxa names are allowed). It is assumed
+    that the taxa names are not repeated in the subsequent blocks of
+    nucleotides.}
 
   \item{Sequential:}{the same criterion than for the interleaved format
     is used to start reading the sequences and the taxa names; the
     sequences are then read until the number of nucleotides specified in
     the first line of the file is reached. This is repeated for each taxa.}
 
+  \item{Clustal:}{this is the format output by the Clustal programs
+    (.aln). It is somehow similar to the interleaved format: the
+    differences being that the dimensions of the data are not indicated
+    in the file, and the names of the sequences are repeated in each block.}
+
   \item{FASTA:}{This looks like the sequential format but the taxa names
     (or rather a description of the sequence) are on separate lines
     beginning with a `greater than' character ``>'' (there may be
     leading spaces before this character). These lines are taken as taxa
     names after removing the ``>'' and the possible leading and trailing
     spaces. All the data in the file before the first sequence is ignored.}
-}
+}}
 \value{
   a matrix or a list (if \code{format = "fasta"}) of DNA sequences
   stored in binary format, or of mode character (if \code{as.character =
@@ -90,7 +95,7 @@ read.dna(file, format = "interleaved", skip = 0,
   \code{\link{read.GenBank}}, \code{\link{write.dna}},
   \code{\link{DNAbin}}, \code{\link{dist.dna}}, \code{\link{woodmouse}}
 }
-\author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
+\author{Emmanuel Paradis}
 \examples{
 ### a small extract from `data(woddmouse)'
 cat("3 40",
@@ -111,6 +116,14 @@ cat("3 40",
 "          ACTAAAAATT ATCAATCACT",
 file = "exdna.txt", sep = "\n")
 ex.dna2 <- read.dna("exdna.txt")
+### ... in clustal format...
+cat("CLUSTAL (ape) multiple sequence alignment", "",
+"No305     NTTCGAAAAACACACCCACTACTAAAANTTATCAGTCACT",
+"No304     ATTCGAAAAACACACCCACTACTAAAAATTATCAACCACT",
+"No306     ATTCGAAAAACACACCCACTACTAAAAATTATCAATCACT",
+"           ************************** ******  ****",
+file = "exdna.txt", sep = "\n")
+ex.dna3 <- read.dna("exdna.txt", format = "clustal")
 ### ... and in FASTA format
 cat("> No305",
 "NTTCGAAAAACACACCCACTACTAAAANTTATCAGTCACT",
@@ -119,10 +132,11 @@ cat("> No305",
 "> No306",
 "ATTCGAAAAACACACCCACTACTAAAAATTATCAATCACT",
 file = "exdna.txt", sep = "\n")
-ex.dna3 <- read.dna("exdna.txt", format = "fasta")
-### These are the same!
+ex.dna4 <- read.dna("exdna.txt", format = "fasta")
+### The first three are the same!
 identical(ex.dna, ex.dna2)
 identical(ex.dna, ex.dna3)
+identical(ex.dna, ex.dna4)
 unlink("exdna.txt") # clean-up
 }
 \keyword{IO}