\name{QbuildAMD}
\alias{QbuildAMD}
\alias{QbuildEMList}
\title{Constructs a StatShop Assessment Model Description from a Q-Matrix}
\description{
  Creates an object of type \code{amd} containing the description of an
  assessment using the specified Q-Matrix and proficiency model.
}
\usage{
QbuildAMD(Qmat, sm, observables, stds = list(diff = 2, disc = 0.5, dinc = 0.4))
QbuildEMList(Qmat, caf, proficiencies, observables,
             emlist = unique(Qmat$EvidenceModel), 
             stds = list(diff = 2, disc = 0.5, dinc = 0.4))
}
\arguments{
  \item{Qmat}{A data frame containing a Q-Matrix (see details) with the
    appropriate evidence models.}
  \item{sm}{A \code{gmModel} object containing a compatable proficiency
    model.} 
  \item{observables}{A list of \code{varDescription} objects containing
    observables.  The
    \code{names} of this object should correspond to the unique values
    of \code{Qmat$ObsName}.}
  \item{stds}{A vector containing values to be used for standard
    devations.  Should conatain values with names \sQuote{diff},
    \sQuote{disc}, and \sQuote{dinc}.}
  \item{caf}{A string giving the ECDID for the CAF for this project.}
  \item{proficiencies}{A list of \code{varDescription} objects containing
    the proficiency variables.}
  \item{emlist}{List of names of evidence models, should correspond to
    values of \code{Qmat$EvidenceModel}.}
}
\details{
  The \code{Qmat} argument specifies which evidence models are required
  for this assessment and the \code{sm} argument provides the student
  model.  This function scans for the unique values of
  \code{Qmat$EvidenceModel} and builds an Evidence Model (as a
  \code{gmModel} object) for each one.  These are then bundled together
  with the \code{sm} to produce a \code{amd} object describing the
  assessment.  The \code{Qmat} object is assumed to be a data frame
  containing a Q-matrix with the special rows and columns listed in
  \code{\link{read.Q}}.

  The function \code{QbuildEMList} is used internally to build the
  evidence model list.  Note is associates the Task Model name for the
  evidence model with the first row of the table using that evidence
  model.  (This assumes that there is not an attempt to pair the
  evidence model with more than one task model.)
}
\value{
  For \sQuote{QbuildAMD} an object of type \code{amd} containing
  \code{sm} and appropriate evidence models.

  For \sQuote{QbuildEMList} a list of objects of type \code{gmModel}
  containing evidence models.
  

}
\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.
}
\author{Russell Almond}
\seealso{\code{\link{read.Q}}, \code{\link{QbuildEM}},
  \code{\link{amd}}, \code{\link{gmModel}},
  \code{\link{addStatsForVars}}, \code{\link{writeAMD}},
  \code{\link{buildDistFromRow}} 
}
\examples{
  readingQ <- read.Q(paste(library(help="SSX")$path,
                           "testFiles","Q-Reading.csv",
                           sep=.Platform$file.sep))


  readingSM <- parseGmModel(paste(library(help="SSX")$path,
                                  "testFiles",
                                  "ReadingCommonality.gm.xml",
                                   sep=.Platform$file.sep)
                           ,"SM")

  # Note, variable names don't quite match, need to adjust them.
  QSkillNames(readingQ)
  readingSM$variables
  QSkillNames(readingQ) <- c("ReadingWordMeaning", "ReadingSpecificInfo",
                          "ReadingConnectInfo", "ReadingSynOrganize")


  # 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"))
       )

  readingAMD <- QbuildAMD(readingQ,readingSM,observables)

  ## Some post-processing steps are typically necessary.  First, add
  ## statistics 
  readingAMD <- addStatsForVars(readingAMD,c("margin"="Bayes Net Margin",
                                         "MAP"="Bayes Net Mode"))
  ## Second, add handlers for missing values.
  readingAMD$missingCodes <-
  list("NA"=MissingCode(type="NA",handler="Ignore",
         xmlCode="X",checksum="X"),   # Mark PINS as NAs.
       "Omit"=MissingCode(type="Omit",handler="Low",
         xmlCode="M",checksum="M"),
       "Not Reached"=MissingCode(type="Not Reached",handler="Ignore",
         xmlCode="N",checksum="N"),
       "Invalid"=MissingCode(type="Ivalid",handler="Error"))

  ## Finally, write it out:
  ## Need a writeable directory.
  outdir <- ifelse(.Platform$OS.type == "windows", "C:/temp","/tmp")
  writeAMD(readingAMD,outdir)
}
\keyword{manip}% at least one, from doc/KEYWORDS