\HeaderA{reverseComplement}{Sequence reversing and complementing}{reverseComplement}
\aliasA{complement}{reverseComplement}{complement}
\aliasA{complement,DNAString-method}{reverseComplement}{complement,DNAString.Rdash.method}
\aliasA{complement,DNAStringSet-method}{reverseComplement}{complement,DNAStringSet.Rdash.method}
\aliasA{complement,MaskedDNAString-method}{reverseComplement}{complement,MaskedDNAString.Rdash.method}
\aliasA{complement,MaskedRNAString-method}{reverseComplement}{complement,MaskedRNAString.Rdash.method}
\aliasA{complement,RNAString-method}{reverseComplement}{complement,RNAString.Rdash.method}
\aliasA{complement,RNAStringSet-method}{reverseComplement}{complement,RNAStringSet.Rdash.method}
\aliasA{complement,XStringViews-method}{reverseComplement}{complement,XStringViews.Rdash.method}
\aliasA{reverse,character-method}{reverseComplement}{reverse,character.Rdash.method}
\aliasA{reverse,MaskedXString-method}{reverseComplement}{reverse,MaskedXString.Rdash.method}
\aliasA{reverse,XString-method}{reverseComplement}{reverse,XString.Rdash.method}
\aliasA{reverse,XStringSet-method}{reverseComplement}{reverse,XStringSet.Rdash.method}
\aliasA{reverse,XStringViews-method}{reverseComplement}{reverse,XStringViews.Rdash.method}
\aliasA{reverseComplement,DNAString-method}{reverseComplement}{reverseComplement,DNAString.Rdash.method}
\aliasA{reverseComplement,DNAStringSet-method}{reverseComplement}{reverseComplement,DNAStringSet.Rdash.method}
\aliasA{reverseComplement,MaskedDNAString-method}{reverseComplement}{reverseComplement,MaskedDNAString.Rdash.method}
\aliasA{reverseComplement,MaskedRNAString-method}{reverseComplement}{reverseComplement,MaskedRNAString.Rdash.method}
\aliasA{reverseComplement,RNAString-method}{reverseComplement}{reverseComplement,RNAString.Rdash.method}
\aliasA{reverseComplement,RNAStringSet-method}{reverseComplement}{reverseComplement,RNAStringSet.Rdash.method}
\aliasA{reverseComplement,XStringViews-method}{reverseComplement}{reverseComplement,XStringViews.Rdash.method}
\aliasA{strrev}{reverseComplement}{strrev}
\keyword{methods}{reverseComplement}
\keyword{manip}{reverseComplement}
\begin{Description}\relax
Use these functions for reversing sequences and/or complementing DNA
or RNA sequences.
\end{Description}
\begin{Usage}
\begin{verbatim}
  ## S4 method for signature 'character':
  reverse(x, ...)
  ## S4 method for signature 'XString':
  reverse(x, ...)
  complement(x, ...)
  reverseComplement(x, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] A character vector, or an \LinkA{XString}{XString}, \LinkA{XStringSet}{XStringSet},
\LinkA{XStringViews}{XStringViews} or \LinkA{MaskedXString}{MaskedXString} object for \code{reverse}.

A \LinkA{DNAString}{DNAString}, \LinkA{RNAString}{RNAString},
\LinkA{DNAStringSet}{DNAStringSet}, \LinkA{RNAStringSet}{RNAStringSet},
\LinkA{XStringViews}{XStringViews} (with \LinkA{DNAString}{DNAString} or \LinkA{RNAString}{RNAString} subject),
\LinkA{MaskedDNAString}{MaskedDNAString} or \LinkA{MaskedRNAString}{MaskedRNAString} object
for \code{complement} and \code{reverseComplement}.

\item[\code{...}] Additional arguments to be passed to or from methods.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Given an \LinkA{XString}{XString} object \code{x}, \code{reverse(x)} returns
an object of the same \LinkA{XString}{XString} base type as \code{x} where letters
in \code{x} have been reordered in the reverse order.

If \code{x} is a \LinkA{DNAString}{DNAString} or \LinkA{RNAString}{RNAString} object,
\code{complement(x)} returns an object where each base in \code{x}
is "complemented" i.e. A, C, G, T in a \LinkA{DNAString}{DNAString} object are replaced
by T, G, C, A respectively and A, C, G, U in a \LinkA{RNAString}{RNAString} object
are replaced by U, G, C, A respectively.

Letters belonging to the IUPAC Extended Genetic Alphabet are also
replaced by their complement (M <-> K, R <-> Y, S <-> S, V <-> B,
W <-> W, H <-> D, N <-> N) and the gap (\code{"-"}) and hard masking
(\code{"+"}) letters are unchanged.

\code{reverseComplement(x)} is equivalent to \code{reverse(complement(x))}
but is faster and more memory efficient.
\end{Details}
\begin{Value}
An object of the same class and length as the original object.
\end{Value}
\begin{SeeAlso}\relax
\LinkA{DNAString-class}{DNAString.Rdash.class},
\LinkA{RNAString-class}{RNAString.Rdash.class},
\LinkA{DNAStringSet-class}{DNAStringSet.Rdash.class},
\LinkA{RNAStringSet-class}{RNAStringSet.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class},
\LinkA{MaskedXString-class}{MaskedXString.Rdash.class},
\code{\LinkA{chartr}{chartr}},
\code{\LinkA{findPalindromes}{findPalindromes}},
\code{\LinkA{IUPAC\_CODE\_MAP}{IUPAC.Rul.CODE.Rul.MAP}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## ---------------------------------------------------------------------
  ## A. SOME SIMPLE EXAMPLES
  ## ---------------------------------------------------------------------

  x <- DNAString("ACGT-YN-")
  reverseComplement(x)

  library(drosophila2probe)
  probes <- DNAStringSet(drosophila2probe)
  probes
  alphabetFrequency(probes, collapse=TRUE)
  rcprobes <- reverseComplement(probes)
  rcprobes
  alphabetFrequency(rcprobes, collapse=TRUE)

  ## ---------------------------------------------------------------------
  ## B. OBTAINING THE MISMATCH PROBES OF A CHIP
  ## ---------------------------------------------------------------------

  pm2mm <- function(probes)
  {
      probes <- DNAStringSet(probes)
      subseq(probes, start=13, end=13) <- complement(subseq(probes, start=13, end=13))
      probes
  }
  mmprobes <- pm2mm(probes)
  mmprobes
  alphabetFrequency(mmprobes, collapse=TRUE)

  ## ---------------------------------------------------------------------
  ## C. SEARCHING THE MINUS STRAND OF A CHROMOSOME
  ## ---------------------------------------------------------------------
  ## Applying reverseComplement() to the pattern before calling
  ## matchPattern() is the recommended way of searching hits on the
  ## minus strand of a chromosome.

  library(BSgenome.Dmelanogaster.UCSC.dm3)
  chrX <- Dmelanogaster$chrX
  pattern <- DNAString("ACCAACNNGGTTG")
  matchPattern(pattern, chrX, fixed=FALSE)  # 3 hits on strand +
  rcpattern <- reverseComplement(pattern)
  rcpattern
  m0 <- matchPattern(rcpattern, chrX, fixed=FALSE)
  m0  # 5 hits on strand -

  ## Applying reverseComplement() to the subject instead of the pattern is not
  ## a good idea for 2 reasons:
  ## (1) Chromosome sequences are generally big and sometimes very big
  ##     so computing the reverse complement of the positive strand will
  ##     take time and memory proportional to its length.
  chrXminus <- reverseComplement(chrX)  # needs to allocate 22M of memory!
  chrXminus
  ## (2) Chromosome locations are generally given relatively to the positive
  ##     strand, even for features located in the negative strand, so after
  ##     doing this:
  m1 <- matchPattern(pattern, chrXminus, fixed=FALSE)
  ##     the start/end of the matches are now relative to the negative strand.
  ##     You need to apply reverseComplement() again on the result if you want
  ##     them to be relative to the positive strand:
  m2 <- reverseComplement(m1)  # allocates 22M of memory, again!
  ##     and finally to apply rev() to sort the matches from left to right
  ##     (5'3' direction) like in m0:
  m3 <- rev(m2) # same as m0, finally!

  ## WARNING: Before you try the example below on human chromosome 1, be aware
  ## that it will require the allocation of about 500Mb of memory!
  if (interactive()) {
    library(BSgenome.Hsapiens.UCSC.hg18)
    chr1 <- Hsapiens$chr1
    matchPattern(pattern, reverseComplement(chr1))  # DON'T DO THIS!
    matchPattern(reverseComplement(pattern), chr1)  # DO THIS INSTEAD
  }
\end{ExampleCode}
\end{Examples}

