\name{optimalEMParams}
\alias{optimalEMParams}
\alias{optimalPMParams}
\title{Find a set of evidence/proficiency model parameters that fit the data.}
\description{

  The function \code{optimalEMParams} does some sort of general
  optimization to try and find an set of evidence model parameters which
  maximizes the weighted likelihood of the given observation conditioned
  on the given latent variables. The function \code{optimalPMParams}
  finds the set of proficiency model parameters which maximize the
  weighted likelihood of the given latent variables.
  
}
\usage{
optimalEMParams(em, obs, latent, weights = 1, background = NA, QQ = Q(em),
                param = parameters(em), control = list(), maxit = 100,
                nowarn = FALSE, Bayes = TRUE)
genericEMoptimizer(em, obs, latent, weights = 1, background = NA, QQ = Q(em),
                  param = parameters(em), control = list(), maxit = 100,
                  nowarn = FALSE, Bayes = TRUE)
optimalPMParams(pm, latent, weights = 1, background = NA, 
                param = parameters(pm), control = list(), maxit = 100,
                nowarn = FALSE, Bayes = TRUE)
genericPMoptimizer(pm, latent, weights = 1, background = NA, 
                   param = parameters(pm), control = list(), maxit = 100,
                   nowarn = FALSE, Bayes = TRUE)
}
\arguments{
  \item{em}{
    An object of class \code{\link{EvidenceModel}}.
  }
  \item{pm}{
    An object of class \code{\link{ProficiencyModel}}.
  }
  \item{obs}{
    A matrix of observation vectors corresponding whose likelihood
    should be evaluated.  It should be true that either
    \code{nrow(latent) == nrow(obs)} or \code{nrow(latent)==1}.  It
    should also be true that \code{ncol(obs) == nobserved(em)}.
  }
  \item{latent}{
    A matrix of latent vectors corresponding to the individuals
    represented in the observations.  It should be true that
    \code{ncol(latent) == ncol(QQ)}.
  }
  \item{weights}{
    A vector of weights which should have either length 1 or
    \code{nrow(obs)}.  If weights are supplied a weighted maximum
    posterior is done instead of the 
  }
  \item{background}{
    An optional set of background (demographic) variables.  Some
    proficiency model types ignore background variables.
  }
  \item{QQ}{A Q-matrix to use (only needed if different from the one
    stored with the evidence model).}
  \item{param}{
    An object representing the initial values for the parameters of
    \code{em}.  The type required is determined by the class of \code{em}.
  }
  \item{control}{
    A list of control flags.  The default method uses
    \code{\link[stats]{optim}} to perform the optimization so the
    control flags used by \code{optim} can be used.
  }
  \item{maxit}{
    The maximum number of iterations to perform.  May want to set this
    to a low value if the call to optimalParams is in the middle of an
    PFEM loop.
  }
  \item{nowarn}{
    Suppresses the warning when the algorithm did not converge.  Again
    useful for call inside of the main PFEM loop.
  }
  \item{Bayes}{
    If true, then the log posterior is optimized rather than the likelihood.
  }
}
\details{

  This attempts to find a set of evidence model parameters that
  maximizes the likelihood of the observed data given the latent
  variables.  If \code{Bayes} is \code{TRUE} it maximizes the log
  posterior instead of the log likelihood.  (This dependents on the fact
  that evidence models and proficiency models contain prior
  distributions for their parameters.)

  The default method generates an error; however, a fairly generic
  utility implementation is available as \code{genericEMoptimzier()},
  which used the function \code{\link[stats]{optim}}.  The quantity to
  be maximized is based on an open implementation protocol, which relies
  on the following other methods:
  \describe{
    \item{\code{\link{pvec}}}{Returns the parameters in a vectorized
  form which can be used by \code{\link[stats]{optim}}.}
    \item{\code{\link{llikeObs}}}{Evaluates the likelihood of the
      observerations.  Returns \code{-Inf} if the parameter values are
      not legal values (e.g., singular covariance matrix).} 
    \item{\code{\link{lpriorEMParam}}}{Evaluates the prior distribution
      of the parameters (only if \code{Bayes==TRUE}). Returns
      \code{-Inf} if the parameter values are 
      not legal values (e.g., singular covariance matrix).}
    \item{\code{\link{lpriorLatent}}}{Evaluates the likelihood of the
      latent variables. Returns \code{-Inf} if the parameter values are
      not legal values (e.g., singular covariance matrix).}
  }

  The \code{genericEMoptimzier()} method uses
  \code{\link[stats]{optim}}.  The values of \code{control} should be
  appropriate for that function.  Note that other implementations may
  find different meanings for \code{control}. 
  The \code{maxit} argument overrides any value in \code{control}.  The
  \code{nowarn} parameter supresses warning messages for lack of
  convergence:  setting \code{nowarn=TRUE} and \code{maxit} to a small
  value is useful for the M-step of a generalized EM algorithm.

}
\value{
  A list with the following components:
  \item{param}{A parameter object of the same class as the \code{param}
    argument containing the optimal parameters.}
  \item{deviance}{ -2 * log likelihood of the observations at the end of
    the run.}
  \item{convergence}{A logical value indicating whether or not the
    optimization converged}
  \item{optout}{A method-specific list of outputs from the
    optimization.}
}
\references{
%% ~put references to the literature/web site here ~
}
\author{ Russell Almond}

\seealso{
  \code{\link{pvec}}, \code{\link{llikeObs}},
  \code{\link{lpriorEMParam}}, \code{\link{lpriorLatent}}
  \code{\link{lpriorPMParam}}
}
\examples{

pm1 <- new("TimelessNormalPM",
           muMean=c(Mechanics=2,Fluency=2),  varWeight=3,
           precMean=solve(matrix(c(.7,.3,.3,.7),2,2)), Sdf=3)

parameters(pm1) <- drawPMParam(pm1)
pparam1 <- drawPMParam(pm1)

stud1k <- drawInitialLatent(pm1,1000,param=pparam1)

##MLE
pparam1.mle <- optimalPMParams(pm1,stud1k,Bayes=FALSE)

##MAP
pparam1.map <- optimalPMParams(pm1,stud1k,Bayes=TRUE)

## Weighted MAP
pparam2.map <- optimalPMParams(pm1,stud1k,Bayes=TRUE,weights=2)


Q <- matrix(c(1,0,1,1),2,2)
em1 <- new("FixedQNormalEM", Q=Q,
           zMean=c(Mechanics=0,Fluency=0),  zStd=diag(c(1,1)),
           Rmean=matrix(c(.7,.3,.3,.7),2,2), Rdf=3,
           hMean=c(1,1,.5), hStd=rep(.25,3))
parameters(em1) <- drawEMParam(em1)
eparam1 <- drawEMParam(em1)

obs1k <- drawObs(em1,stud1k,param=eparam1)

##MLE
eparam1.mle <- optimalEMParams(em1,obs1k,stud1k,Bayes=FALSE)
eparam1a.mle <- optimalEMParams(em1,obs1k,stud1k,param=eparam1.mle$param,Bayes=FALSE)

##MAP
eparam1.map <- optimalEMParams(em1,obs1k,stud1k,Bayes=TRUE)


}
\keyword{ manip }