\HeaderA{translate}{DNA/RNA transcription and translation}{translate}
\aliasA{cDNA}{translate}{cDNA}
\aliasA{codons}{translate}{codons}
\aliasA{codons,DNAString-method}{translate}{codons,DNAString.Rdash.method}
\aliasA{codons,MaskedDNAString-method}{translate}{codons,MaskedDNAString.Rdash.method}
\aliasA{codons,MaskedRNAString-method}{translate}{codons,MaskedRNAString.Rdash.method}
\aliasA{codons,RNAString-method}{translate}{codons,RNAString.Rdash.method}
\aliasA{dna2rna}{translate}{dna2rna}
\aliasA{rna2dna}{translate}{rna2dna}
\aliasA{transcribe}{translate}{transcribe}
\aliasA{translate,DNAString-method}{translate}{translate,DNAString.Rdash.method}
\aliasA{translate,DNAStringSet-method}{translate}{translate,DNAStringSet.Rdash.method}
\aliasA{translate,MaskedDNAString-method}{translate}{translate,MaskedDNAString.Rdash.method}
\aliasA{translate,MaskedRNAString-method}{translate}{translate,MaskedRNAString.Rdash.method}
\aliasA{translate,RNAString-method}{translate}{translate,RNAString.Rdash.method}
\aliasA{translate,RNAStringSet-method}{translate}{translate,RNAStringSet.Rdash.method}
\keyword{methods}{translate}
\keyword{manip}{translate}
\begin{Description}\relax
Functions for transcription and/or translation of DNA or RNA
sequences, and related utilities.
\end{Description}
\begin{Usage}
\begin{verbatim}
  ## Transcription:
  transcribe(x)
  cDNA(x)

  ## Translation:
  codons(x)
  translate(x)

  ## Related utilities:
  dna2rna(x)
  rna2dna(x)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A \LinkA{DNAString}{DNAString} object for \code{transcribe} and \code{dna2rna}.

An \LinkA{RNAString}{RNAString} object for \code{cDNA} and \code{rna2dna}.

A \LinkA{DNAString}{DNAString}, \LinkA{RNAString}{RNAString}, \LinkA{MaskedDNAString}{MaskedDNAString} or
\LinkA{MaskedRNAString}{MaskedRNAString} object for \code{codons}.

A \LinkA{DNAString}{DNAString}, \LinkA{RNAString}{RNAString}, \LinkA{DNAStringSet}{DNAStringSet},
\LinkA{RNAStringSet}{RNAStringSet}, \LinkA{MaskedDNAString}{MaskedDNAString} or \LinkA{MaskedRNAString}{MaskedRNAString}
object for \code{translate}.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{transcribe} reproduces the biological process of DNA
transcription that occurs in the cell. It takes the naive approach
to treat the whole sequence \code{x} as if it was a single exon.
See \code{\LinkA{extractTranscripts}{extractTranscripts}} for a more powerful version
that allows the user to extract a set of transcripts specified by
the starts and ends of their exons as well as the strand from
which the transcript is coming.

\code{cDNA} reproduces the process of synthesizing complementary DNA
from a mature mRNA template.

\code{translate} reproduces the biological process of RNA
translation that occurs in the cell.
The input of the function can be either RNA or coding DNA.
The Standard Genetic Code (see \code{?\LinkA{GENETIC\_CODE}{GENETIC.Rul.CODE}}) is
used to translate codons into amino acids.
\code{codons} is a utility for extracting the codons involved
in this translation without translating them. 

\code{dna2rna} and \code{rna2dna} are low-level utilities for
converting sequences from DNA to RNA and vice-versa.
All what this converstion does is to replace each occurrence of T
by a U and vice-versa.
\end{Details}
\begin{Value}
An \LinkA{RNAString}{RNAString} object for \code{transcribe} and \code{dna2rna}.

A \LinkA{DNAString}{DNAString} object for \code{cDNA} and \code{rna2dna}.

Note that if the sequence passed to \code{transcribe} or \code{cDNA}
is considered to be oriented 5'-3', then the returned sequence is
oriented 3'-5'.

An \LinkA{XStringViews}{XStringViews} object with 1 view per codon for \code{codons}.
When \code{x} is a \LinkA{MaskedDNAString}{MaskedDNAString} or \LinkA{MaskedRNAString}{MaskedRNAString}
object, its masked parts are interpreted as introns and filled with
the + letter in the returned object. Therefore codons that span across
masked regions are represented by views that have a width > 3 and
contain the + letter. Note that each view is guaranteed to contain
exactly 3 base letters.

An \LinkA{AAString}{AAString} object for \code{translate}.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{reverseComplement}{reverseComplement}},
\code{\LinkA{GENETIC\_CODE}{GENETIC.Rul.CODE}},
\LinkA{DNAString-class}{DNAString.Rdash.class},
\LinkA{RNAString-class}{RNAString.Rdash.class},
\LinkA{AAString-class}{AAString.Rdash.class},
\LinkA{XStringSet-class}{XStringSet.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class},
\LinkA{MaskedXString-class}{MaskedXString.Rdash.class}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  file <- system.file("extdata", "someORF.fa", package="Biostrings")
  x <- read.DNAStringSet(file)
  x

  ## The first and last 1000 nucleotides are not part of the ORFs:
  x <- DNAStringSet(x, start=1001, end=-1001)

  ## Before calling translate() on an ORF, we need to mask the introns
  ## if any. We can get this information fron the SGD database
  ## (http://www.yeastgenome.org/).
  ## According to SGD, the 1st ORF (YAL001C) has an intron at 71..160
  ## (see http://db.yeastgenome.org/cgi-bin/locus.pl?locus=YAL001C)
  y1 <- x[[1]]
  mask1 <- Mask(length(y1), start=71, end=160)
  masks(y1) <- mask1
  y1
  translate(y1)

  ## Codons
  codons(y1)
  which(width(codons(y1)) != 3)
  codons(y1)[20:28]
\end{ExampleCode}
\end{Examples}

