man/read.dna.Rd

   1 \name{read.dna}
   2 \alias{read.dna}
   3 \title{Read DNA Sequences in a File}
   4 \usage{
   5 read.dna(file, format = "interleaved", skip = 0,
   6          nlines = 0, comment.char = "#", seq.names = NULL,
   7          as.character = FALSE)
   8 }
   9 \arguments{
  10   \item{file}{a file name specified by either a variable of mode character,
  11     or a double-quoted string.}
  12   \item{format}{a character string specifying the format of the DNA
  13     sequences. Three choices are possible: \code{"interleaved"},
  14     \code{"sequential"}, or \code{"fasta"}, or any unambiguous
  15     abbreviation of these.}
  16   \item{skip}{the number of lines of the input file to skip before
  17     beginning to read data.}
  18   \item{nlines}{the number of lines to be read (by default the file is
  19     read untill its end).}
  20   \item{comment.char}{a single character, the remaining of the line
  21     after this character is ignored.}
  22   \item{seq.names}{the names to give to each sequence; by default the
  23     names read in the file are used.}
  24   \item{as.character}{a logical controlling whether to return the
  25     sequences as an object of class \code{"DNAbin"} (the default).}
  26 }
  27 \description{
  28   This function reads DNA sequences in a file, and returns a matrix or a
  29   list of DNA sequences with the names of the taxa read in the file as
  30   rownames or names, respectively. By default, the sequences are stored
  31   in binary format, otherwise (if \code{as.character = "TRUE"}) in lower
  32   case.
  33 }
  34 \details{
  35   This function follows the interleaved and sequential formats defined
  36   in PHYLIP (Felsenstein, 1993) but with the original feature than there
  37   is no restriction on the lengths of the taxa names (though a data file
  38   with 10-characters-long taxa names is fine as well). For these two
  39   formats, the first line of the file must contain the dimensions of the
  40   data (the numbers of taxa and the numbers of nucleotides); the
  41   sequences are considered as aligned and thus must be of the same
  42   lengths for all taxa. For the FASTA format, the conventions defined in
  43   the URL below (see References) are followed; the sequences are taken as
  44   non-aligned. For all formats, the nucleotides can be arranged in any
  45   way with blanks and line-breaks inside (with the restriction that the
  46   first ten nucleotides must be contiguous for the interleaved and
  47   sequential formats, see below). The names of the sequences are read in
  48   the file unless the `seq.names' option is used. Particularities for
  49   each format are detailed below.
  50
  51   \item{Interleaved:}{the function starts to read the sequences when it
  52     finds 10 contiguous characters belonging to the ambiguity code of
  53     the IUPAC (namely A, C, G, T, U, M, R, W, S, Y, K, V, H, D, B, and
  54     N, upper- or lowercase, so you might run into trouble if you have a
  55     taxa name with 10 contiguous letters among these!) All characters
  56     before the sequences are taken as the taxa names after removing the
  57     leading and trailing spaces (so spaces in a taxa name are
  58     allowed). It is assumed that the taxa names are not repeated in the
  59     subsequent blocks of nucleotides.}
  60
  61   \item{Sequential:}{the same criterion than for the interleaved format
  62     is used to start reading the sequences and the taxa names; the
  63     sequences are then read until the number of nucleotides specified in
  64     the first line of the file is reached. This is repeated for each taxa.}
  65
  66   \item{FASTA:}{This looks like the sequential format but the taxa names
  67     (or rather a description of the sequence) are on separate lines
  68     beginning with a `greater than' character ``>'' (there may be
  69     leading spaces before this character). These lines are taken as taxa
  70     names after removing the ``>'' and the possible leading and trailing
  71     spaces. All the data in the file before the first sequence is ignored.}
  72 }
  73 \value{
  74   a matrix or a list (if \code{format = "fasta"}) of DNA sequences
  75   stored in binary format, or of mode character (if \code{as.character =
  76     "TRUE"}).
  77 }
  78 \references{
  79   Anonymous. FASTA format description.
  80   \url{http://www.ncbi.nlm.nih.gov/BLAST/fasta.html}
  81
  82   Anonymous. IUPAC ambiguity codes.
  83   \url{http://www.ncbi.nlm.nih.gov/SNP/iupac.html}
  84
  85   Felsenstein, J. (1993) Phylip (Phylogeny Inference Package) version
  86   3.5c. Department of Genetics, University of Washington.
  87   \url{http://evolution.genetics.washington.edu/phylip/phylip.html}
  88 }
  89 \seealso{
  90   \code{\link{read.GenBank}}, \code{\link{write.dna}},
  91   \code{\link{DNAbin}}, \code{\link{dist.dna}}, \code{\link{woodmouse}}
  92 }
  93 \author{Emmanuel Paradis \email{Emmanuel.Paradis@mpl.ird.fr}}
  94 \examples{
  95 ### a small extract from `data(woddmouse)'
  96 cat("3 40",
  97 "No305     NTTCGAAAAACACACCCACTACTAAAANTTATCAGTCACT",
  98 "No304     ATTCGAAAAACACACCCACTACTAAAAATTATCAACCACT",
  99 "No306     ATTCGAAAAACACACCCACTACTAAAAATTATCAATCACT",
 100 file = "exdna.txt", sep = "\n")
 101 ex.dna <- read.dna("exdna.txt", format = "sequential")
 102 str(ex.dna)
 103 ex.dna
 104 ### the same data in interleaved format...
 105 cat("3 40",
 106 "No305     NTTCGAAAAA CACACCCACT",
 107 "No304     ATTCGAAAAA CACACCCACT",
 108 "No306     ATTCGAAAAA CACACCCACT",
 109 "          ACTAAAANTT ATCAGTCACT",
 110 "          ACTAAAAATT ATCAACCACT",
 111 "          ACTAAAAATT ATCAATCACT",
 112 file = "exdna.txt", sep = "\n")
 113 ex.dna2 <- read.dna("exdna.txt")
 114 ### ... and in FASTA format
 115 cat("> No305",
 116 "NTTCGAAAAACACACCCACTACTAAAANTTATCAGTCACT",
 117 "> No304",
 118 "ATTCGAAAAACACACCCACTACTAAAAATTATCAACCACT",
 119 "> No306",
 120 "ATTCGAAAAACACACCCACTACTAAAAATTATCAATCACT",
 121 file = "exdna.txt", sep = "\n")
 122 ex.dna3 <- read.dna("exdna.txt", format = "fasta")
 123 ### These are the same!
 124 identical(ex.dna, ex.dna2)
 125 identical(ex.dna, ex.dna3)
 126 unlink("exdna.txt") # clean-up
 127 }
 128 \keyword{IO}