\HeaderA{nucleotideFrequency}{Calculate the frequency of oligonucleotides in a DNA
or RNA sequence (and other related functions)}{nucleotideFrequency}
\aliasA{dinucleotideFrequency}{nucleotideFrequency}{dinucleotideFrequency}
\aliasA{mkAllStrings}{nucleotideFrequency}{mkAllStrings}
\aliasA{nucleotideFrequencyAt}{nucleotideFrequency}{nucleotideFrequencyAt}
\aliasA{nucleotideFrequencyAt,XStringSet-method}{nucleotideFrequency}{nucleotideFrequencyAt,XStringSet.Rdash.method}
\aliasA{nucleotideFrequencyAt,XStringViews-method}{nucleotideFrequency}{nucleotideFrequencyAt,XStringViews.Rdash.method}
\aliasA{oligonucleotideFrequency}{nucleotideFrequency}{oligonucleotideFrequency}
\methaliasA{oligonucleotideFrequency}{nucleotideFrequency}{oligonucleotideFrequency}
\aliasA{oligonucleotideFrequency,MaskedXString-method}{nucleotideFrequency}{oligonucleotideFrequency,MaskedXString.Rdash.method}
\aliasA{oligonucleotideFrequency,XString-method}{nucleotideFrequency}{oligonucleotideFrequency,XString.Rdash.method}
\aliasA{oligonucleotideFrequency,XStringSet-method}{nucleotideFrequency}{oligonucleotideFrequency,XStringSet.Rdash.method}
\aliasA{oligonucleotideFrequency,XStringViews-method}{nucleotideFrequency}{oligonucleotideFrequency,XStringViews.Rdash.method}
\aliasA{oligonucleotideTransitions}{nucleotideFrequency}{oligonucleotideTransitions}
\aliasA{trinucleotideFrequency}{nucleotideFrequency}{trinucleotideFrequency}
\keyword{methods}{nucleotideFrequency}
\keyword{manip}{nucleotideFrequency}
\begin{Description}\relax
Given a DNA or RNA sequence (or a set of DNA or RNA sequences),
the \code{oligonucleotideFrequency} function computes the frequency
of all possible oligonucleotides of a given length (called the "width"
in this particular context).

The \code{dinucleotideFrequency} and \code{trinucleotideFrequency}
functions are convenient wrappers for calling \code{oligonucleotideFrequency}
with \code{width=2} and \code{width=3}, respectively.

The \code{nucleotideFrequencyAt} function computes the frequency
of the short sequences formed by extracting the nucleotides found
at some fixed positions from each sequence of a set of DNA or RNA
sequences.

In this man page we call "DNA input" (or "RNA input") an
\LinkA{XString}{XString}, \LinkA{XStringSet}{XStringSet}, \LinkA{XStringViews}{XStringViews} or
\LinkA{MaskedXString}{MaskedXString} object of base type DNA (or RNA).
\end{Description}
\begin{Usage}
\begin{verbatim}
  oligonucleotideFrequency(x, width, as.prob=FALSE, freq=FALSE, as.array=FALSE,
                           fast.moving.side="right", with.labels=TRUE, ...)

  ## S4 method for signature 'XStringSet':
  oligonucleotideFrequency(x,
      width, as.prob=FALSE, freq=FALSE, as.array=FALSE,
      fast.moving.side="right", with.labels=TRUE, simplify.as="matrix")

  dinucleotideFrequency(x, as.prob=FALSE, freq=FALSE, as.matrix=FALSE,
                        fast.moving.side="right", with.labels=TRUE, ...)
  trinucleotideFrequency(x, as.prob=FALSE, freq=FALSE, as.array=FALSE,
                         fast.moving.side="right", with.labels=TRUE, ...)

  nucleotideFrequencyAt(x, at, as.prob=FALSE, freq=FALSE, as.array=TRUE,
                        fast.moving.side="right", with.labels=TRUE, ...)

  ## Some related functions:
  oligonucleotideTransitions(x, left=1, right=1, as.prob=FALSE, freq=FALSE)
  mkAllStrings(alphabet, width, fast.moving.side="right")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] Any DNA or RNA input for the \code{*Frequency} and
\code{oligonucleotideTransitions} functions.

An \LinkA{XStringSet}{XStringSet} or \LinkA{XStringViews}{XStringViews} object of base type DNA or RNA
for \code{nucleotideFrequencyAt}.

\item[\code{width}] The number of nucleotides per oligonucleotide for
\code{oligonucleotideFrequency}.

The number of letters per string for \code{mkAllStrings}.

\item[\code{at}] An integer vector containing the positions to look at in each element
of \code{x}.

\item[\code{as.prob}] If \code{TRUE} then probabilities are reported,
otherwise counts (the default).

\item[\code{freq}] This argument is deprecated.
Please use the \code{as.prob} argument instead.

\item[\code{as.array,as.matrix}] Controls the "shape" of the returned object.
If \code{TRUE} (the default for \code{nucleotideFrequencyAt})
then it's a numeric matrix (or array),
otherwise it's just a "flat" numeric vector i.e. a
vector with no dim attribute (the default for the
\code{*Frequency} functions).

\item[\code{fast.moving.side}] Which side of the strings should move fastest?
Note that, when \code{as.array} is TRUE, then the supplied value
is ignored and the effective value is \code{"left"}.

\item[\code{with.labels}] If \code{TRUE} then the returned object is named.

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

\item[\code{simplify.as}] Together with the \code{as.array} and \code{as.matrix}
arguments, controls the "shape" of the returned object
when the input \code{x} is an \LinkA{XStringSet}{XStringSet} or
\LinkA{XStringViews}{XStringViews} object.
Supported \code{simplify.as} values are \code{"matrix"}
(the default), \code{"list"} and \code{"collapsed"}.
If \code{simplify.as} is \code{"matrix"}, the returned
object is a matrix with \code{length(x)} rows where the
\code{i}-th row contains the frequencies for \code{x[[i]]}.
If \code{simplify.as} is \code{"list"}, the returned
object is a list of the same length as \code{length(x)}
where the \code{i}-th element contains the frequencies
for \code{x[[i]]}.
If \code{simplify.as} is \code{"collapsed"}, then the
the frequencies are computed for the entire object \code{x}
as a whole (i.e. frequencies cumulated across all sequences
in \code{x}).

\item[\code{left, right}] The number of nucleotides per oligonucleotide for the rows
and columns respectively in the transition matrix created
by \code{oligonucleotideTransitions}.

\item[\code{alphabet}] The alphabet to use to make the strings.

\end{ldescription}
\end{Arguments}
\begin{Value}
If \code{x} is an \LinkA{XString}{XString} or \LinkA{MaskedXString}{MaskedXString} object,
the \code{*Frequency} functions return a numeric vector of length
\code{4\textasciicircum{}width}. If \code{as.array} (or \code{as.matrix}) is \code{TRUE},
then this vector is formatted as an array (or matrix).
If \code{x} is an \LinkA{XStringSet}{XStringSet} or \LinkA{XStringViews}{XStringViews} object,
the returned object has the shape specified by the \code{simplify.as}
argument.
\end{Value}
\begin{Author}\relax
H. Pages and P. Aboyoun
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{alphabetFrequency}{alphabetFrequency}},
\code{\LinkA{alphabet}{alphabet}},
\code{\LinkA{hasLetterAt}{hasLetterAt}},
\LinkA{XString-class}{XString.Rdash.class},
\LinkA{XStringSet-class}{XStringSet.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class},
\LinkA{MaskedXString-class}{MaskedXString.Rdash.class},
\code{\LinkA{GENETIC\_CODE}{GENETIC.Rul.CODE}},
\code{\LinkA{AMINO\_ACID\_CODE}{AMINO.Rul.ACID.Rul.CODE}},
\code{\LinkA{reverse,XString-method}{reverse,XString.Rdash.method}},
\code{\LinkA{rev}{rev}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## ---------------------------------------------------------------------
  ## A. BASIC *Frequency() EXAMPLES
  ## ---------------------------------------------------------------------
  data(yeastSEQCHR1)
  yeast1 <- DNAString(yeastSEQCHR1)

  dinucleotideFrequency(yeast1)
  trinucleotideFrequency(yeast1)
  oligonucleotideFrequency(yeast1, 4)

  ## Get the less and most represented 6-mers:
  f6 <- oligonucleotideFrequency(yeast1, 6)
  f6[f6 == min(f6)]
  f6[f6 == max(f6)]

  ## Get the result as an array:
  tri <- trinucleotideFrequency(yeast1, as.array=TRUE)
  tri["A", "A", "C"] # == trinucleotideFrequency(yeast1)["AAC"]
  tri["T", , ] # frequencies of trinucleotides starting with a "T"

  ## With input made of multiple sequences:
  library(drosophila2probe)
  probes <- DNAStringSet(drosophila2probe)
  dfmat <- dinucleotideFrequency(probes)  # a big matrix
  dinucleotideFrequency(probes, simplify.as="collapsed")
  dinucleotideFrequency(probes, simplify.as="collapsed", as.matrix=TRUE)

  ## ---------------------------------------------------------------------
  ## B. nucleotideFrequencyAt()
  ## ---------------------------------------------------------------------
  nucleotideFrequencyAt(probes, 13)
  nucleotideFrequencyAt(probes, c(13, 20))
  nucleotideFrequencyAt(probes, c(13, 20), as.array=FALSE)

  ## nucleotideFrequencyAt() can be used to answer questions like: "how
  ## many probes in the drosophila2 chip have T, G, T, A at position
  ## 2, 4, 13 and 20, respectively?"
  nucleotideFrequencyAt(probes, c(2, 4, 13, 20))["T", "G", "T", "A"]
  ## or "what's the probability to have an A at position 25 if there is
  ## one at position 13?"
  nf <- nucleotideFrequencyAt(probes, c(13, 25))
  sum(nf["A", "A"]) / sum(nf["A", ])
  ## Probabilities to have other bases at position 25 if there is an A
  ## at position 13:
  sum(nf["A", "C"]) / sum(nf["A", ])  # C
  sum(nf["A", "G"]) / sum(nf["A", ])  # G
  sum(nf["A", "T"]) / sum(nf["A", ])  # T

  ## See ?hasLetterAt for another way to get those results.

  ## ---------------------------------------------------------------------
  ## C. oligonucleotideTransitions()
  ## ---------------------------------------------------------------------
  ## Get nucleotide transition matrices for yeast1
  oligonucleotideTransitions(yeast1)
  oligonucleotideTransitions(yeast1, 2, as.prob=TRUE)

  ## ---------------------------------------------------------------------
  ## D. ADVANCED *Frequency() EXAMPLES
  ## ---------------------------------------------------------------------
  ## Note that when dropping the dimensions of the 'tri' array, elements
  ## in the resulting vector are ordered as if they were obtained with
  ## 'fast.moving.side="left"':
  triL <- trinucleotideFrequency(yeast1, fast.moving.side="left")
  all(as.vector(tri) == triL) # TRUE

  ## Convert the trinucleotide frequency into the amino acid frequency
  ## based on translation:
  tri1 <- trinucleotideFrequency(yeast1)
  names(tri1) <- GENETIC_CODE[names(tri1)]
  sapply(split(tri1, names(tri1)), sum) # 12512 occurrences of the stop codon

  ## When the returned vector is very long (e.g. width >= 10), using
  ## 'with.labels=FALSE' can improve performance significantly.
  ## Here for example, the observed speed up is between 25x and 500x:
  f12 <- oligonucleotideFrequency(yeast1, 12, with.labels=FALSE) # very fast!

  ## Spome related functions:
  dict1 <- mkAllStrings(LETTERS[1:3], 4)
  dict2 <- mkAllStrings(LETTERS[1:3], 4, fast.moving.side="left")
  identical(reverse(dict1), dict2) # TRUE 
\end{ExampleCode}
\end{Examples}

