\name{QbuildEM}
\alias{QbuildEM}
\title{Builds a gmModel for an evidence model from a Q-Matrix}
\description{
  Creates a \code{gmModel} object representing an evidence model
  contained in one or more rows of a Q-Matrix.  This selects rows for
  which \code{Qmat$EvidenceModel == emname},
  \code{Qmat$TaskModel == tmname}, and
  \code{Qmat$TaskName == taskame} and builds a corresponding evidence
  model.
}
\usage{
QbuildEM(Qmat, emname, tmname, caf, proficiencies, observables,
         taskname = Qmat$TaskName[Qmat$EvidenceModel == emname &
                                  Qmat$TaskModel == tmname][1],
stds = list(diff = 2, disc = 0.5, dinc = 0.4))
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{Qmat}{A data frame containing a Q-Matrix (see \code{\link{read.Q}}).}
  \item{emname}{Name of the evidence model as a string (not full ECDID).}
  \item{tmname}{Name of the task model as a string (not full ECDID).}
  \item{caf}{Prefix for ECDID. TaskID and LinkID for model is formed by
    pasting task and evidence name to this prefix.}
  \item{proficiencies}{A collection of \code{varDescription} objects for
    proficiency variables.}
  \item{observables}{A collection of \code{varDescription} objects for
    observables and other evidence model variables.}
  \item{taskname}{Name of the task.  The default looks for the first
    task which matches \code{emname} and \code{tmname}.}
  \item{stds}{A vector containing values to be used for standard
    devations.  Should conatain values with names \sQuote{diff},
    \sQuote{disc}, and \sQuote{dinc}.}
}
\details{
  After filtering the Q-Matrix on the \code{emname}, \code{tmname} and
  \code{taskname}, every row that remains should correspond to an
  observable variable.  It builds a distribution for each row and then
  packages them into a \code{gmModel} structure.  The \code{gmModel}
  requires a collection of \code{varDescription} objects which is drawn
  from the \code{proficiencies} and \code{observable.} arguments.
}
\value{
  A \code{gmModel} object containing an evidence model.
}
\author{Russell Almond}
\section{Under Construction}{
  Haven't really thought through yet how to handle dependencies among
  observable and local evidence model variables (e.g., a context
  effect).  May be a way to trick the system into regarding them as
  extra rows of the Q-Matrix.

  Currently much of the work is done by \code{\link{buildDistFromRow}},
  see that function for current limitations.
}
\seealso{\code{\link{QbuildAMD}}, \code{\link{gmModel}},
         \code{\link{varDescription}}, \code{\link{read.Q}},
	 \code{\link{ECDID}}, \code{\link{buildDistFromRow}}
}
\examples{
  readingQ <- read.Q(paste(library(help="SSX")$path,
                           "testFiles","Q-Reading.csv",
                           sep=.Platform$file.sep))


  proficiencies <- QProficiencyVars(QSkillNames(readingQ),
                      c("High","Medium","Low"))

  # Observable for MC and three level of partial credit items.
  observables <-
    list(isCorrect=varDescription(name="isCorrect",role="Observable",
                      levels=c("1","0")),
         pc2=varDescription(name="pc2",role="Observable",
         levels=c("2","1","0")),
         pc3=varDescription(name="pc3",role="Observable",
           levels=c("3","2","1","0")),
         pc4=varDescription(name="pc4",role="Observable",
           levels=c("4","3","2","1","0"))
       )

  ## Build EM for first row of proficiency model
  EM1 <- QbuildEM(readingQ,readingQ$EvidenceModel[1],
                  readingQ$TaskModel[1], "ecd://test/testCAF/",
                  proficiencies, observables)

}
\keyword{internal}% at least one, from doc/KEYWORDS