\HeaderA{matchPWM}{PWM creating, matching, and related utilities}{matchPWM}
\aliasA{countPWM}{matchPWM}{countPWM}
\aliasA{countPWM,character-method}{matchPWM}{countPWM,character.Rdash.method}
\aliasA{countPWM,DNAString-method}{matchPWM}{countPWM,DNAString.Rdash.method}
\aliasA{countPWM,MaskedDNAString-method}{matchPWM}{countPWM,MaskedDNAString.Rdash.method}
\aliasA{countPWM,XStringViews-method}{matchPWM}{countPWM,XStringViews.Rdash.method}
\aliasA{matchPWM,character-method}{matchPWM}{matchPWM,character.Rdash.method}
\aliasA{matchPWM,DNAString-method}{matchPWM}{matchPWM,DNAString.Rdash.method}
\aliasA{matchPWM,MaskedDNAString-method}{matchPWM}{matchPWM,MaskedDNAString.Rdash.method}
\aliasA{matchPWM,XStringViews-method}{matchPWM}{matchPWM,XStringViews.Rdash.method}
\aliasA{maxScore}{matchPWM}{maxScore}
\aliasA{maxScore,ANY-method}{matchPWM}{maxScore,ANY.Rdash.method}
\aliasA{maxWeights}{matchPWM}{maxWeights}
\aliasA{maxWeights,matrix-method}{matchPWM}{maxWeights,matrix.Rdash.method}
\aliasA{minScore}{matchPWM}{minScore}
\aliasA{minScore,ANY-method}{matchPWM}{minScore,ANY.Rdash.method}
\aliasA{minWeights}{matchPWM}{minWeights}
\aliasA{minWeights,matrix-method}{matchPWM}{minWeights,matrix.Rdash.method}
\aliasA{PWM}{matchPWM}{PWM}
\aliasA{PWM,character-method}{matchPWM}{PWM,character.Rdash.method}
\aliasA{PWM,DNAStringSet-method}{matchPWM}{PWM,DNAStringSet.Rdash.method}
\aliasA{PWMscore}{matchPWM}{PWMscore}
\aliasA{PWMscoreStartingAt}{matchPWM}{PWMscoreStartingAt}
\aliasA{reverseComplement,matrix-method}{matchPWM}{reverseComplement,matrix.Rdash.method}
\aliasA{unitScale}{matchPWM}{unitScale}
\keyword{methods}{matchPWM}
\keyword{manip}{matchPWM}
\keyword{utilities}{matchPWM}
\begin{Description}\relax
Position Weight Matrix (PWM) creating, matching, and related utilities
for DNA data. (PWM for amino acid sequences are not supported.)
\end{Description}
\begin{Usage}
\begin{verbatim}
  PWM(x, type = c("log2probratio", "prob"),
      prior.params = c("A"=0.25, "C"=0.25, "G"=0.25, "T"=0.25))

  matchPWM(pwm, subject, min.score="80%", ...)
  countPWM(pwm, subject, min.score="80%", ...)
  PWMscoreStartingAt(pwm, subject, starting.at=1)

  ## Utility functions for basic manipulation of the Position Weight Matrix
  maxWeights(x)
  minWeights(x)
  maxScore(x)
  minScore(x)
  unitScale(x)
  ## S4 method for signature 'matrix':
  reverseComplement(x, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] For \code{PWM} a character string or DNAStringSet whose elements all have
the same number of characters.

For \code{maxWeights}, \code{minWeights}, \code{maxScore}, \code{minScore},
\code{unitScale} , and \code{reverseComplement} a numeric matrix with row
names A, C, G and T representing a Position Weight Matrix.

\item[\code{type}] The type of position weight matrix, either "log2probratio" or "prob".
See Details section for more information.

\item[\code{prior.params}] A positive numeric vector, which represents the parameters of the
Dirichlet conjugate prior, with names A, C, G, and T.
See Details section for more information.

\item[\code{pwm}] A numeric matrix with row names A, C, G and T representing a Position
Weight Matrix.

\item[\code{subject}] An \LinkA{DNAString}{DNAString}, \LinkA{XStringViews}{XStringViews} or \LinkA{MaskedDNAString}{MaskedDNAString}
object for \code{matchPWM} and \code{countPWM}.

A \LinkA{DNAString}{DNAString} object containing the subject sequence.

\item[\code{min.score}] The minimum score for counting a match.
Can be given as a character string containing a percentage (e.g.
\code{"85\%"}) of the highest possible score or as a single number.

\item[\code{starting.at}] An integer vector specifying the starting positions of the
Position Weight Matrix relatively to the subject.

\item[\code{...}] Additional arguments for methods.

\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{PWM} function uses a multinomial model with a Dirichlet conjugate
prior to calculate the estimated probability of base b at position i. As
mentioned in the Arguments section, \code{prior.params} supplies the
parameters for the DNA bases A, C, G, and T in the Dirichlet prior. These
values result in a position independent initial estimate of the probabilities
for the bases to be
\code{priorProbs = prior.params/sum(prior.params)} and the
posterior (data infused) estimate for the probabilities for the bases in each
of the positions to be
\code{postProbs = (consensusMatrix(x) + prior.params)/(length(x) + sum(prior.params))}.
When \code{type = "log2probratio"}, the PWM = \code{unitScale(log2(postProbs/priorProbs))}.
When \code{type = "prob"}, the PWM = \code{unitScale(postProbs)}.
\end{Details}
\begin{Value}
A numeric matrix representing the Position Weight Matrix for \code{PWM}.

A numeric vector containing the Position Weight Matrix-based scores
for \code{PWMscoreStartingAt}.

An \LinkA{XStringViews}{XStringViews} object for \code{matchPWM}.

A single integer for \code{countPWM}.

A vector containing the max weight for each position in \code{pwm}
for \code{maxWeights}.

A vector containing the min weight for each position in \code{pwm}
for \code{minWeights}.

The highest possible score for a given Position Weight Matrix for
\code{maxScore}.

The lowest possible score for a given Position Weight Matrix for
\code{maxScore}.

The modified numeric matrix given by
\code{(x - minScore(x)/ncol(x))/(maxScore(x) - minScore(x))} for
\code{unitScale}.

A PWM obtained by reverting the column order in PWM \code{x} and by
reassigning each row to its complementary nucleotide
for \code{reverseComplement}.
\end{Value}
\begin{Author}\relax
H. Pages and P. Aboyoun
\end{Author}
\begin{References}\relax
Wasserman, WW, Sandelin, A., (2004) Applied bioinformatics for the identification of
regulatory elements, Nat Rev Genet., 5(4):276-87.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{matchPattern}{matchPattern}},
\code{\LinkA{reverseComplement}{reverseComplement}},
\LinkA{DNAString-class}{DNAString.Rdash.class},
\LinkA{XStringViews-class}{XStringViews.Rdash.class}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  ## Data setup
  data(HNF4alpha)
  library(BSgenome.Dmelanogaster.UCSC.dm3)
  chr3R <- Dmelanogaster$chr3R
  chr3R

  ## Create a PWM and perform some general routines
  pwm <- PWM(HNF4alpha)
  round(pwm, 2)
  maxWeights(pwm)
  maxScore(pwm)
  reverseComplement(pwm)

  ## Score the first 5 positions
  PWMscoreStartingAt(pwm, unmasked(chr3R), starting.at=1:5)

  ## Match the plus strand
  matchPWM(pwm, chr3R)
  countPWM(pwm, chr3R)

  ## Match the minus strand
  matchPWM(reverseComplement(pwm), chr3R)
\end{ExampleCode}
\end{Examples}

