\name{QtoPD}
\alias{QtoPD}
\title{Generates a Pretest Description from a Q-Matrix.}
\description{
  Generates a \code{\link{PretestDescription}} object based on the tasks
  found in a particular, Q-Matrix (see \code{\link{read.Q}}).
}
\usage{
QtoPD(Qmat, caf, observables, itemColPrefix = "Item",
      integerCode = NULL, appID = deparse(substitute(Qmat)),
      uidPrefix = "", missingHandlers = list(), demographics = list(),
      statistics = list()) 
}
\arguments{
  \item{Qmat}{A data frame containing a Q-Matrix (see
    \code{\link{read.Q}}).  Only the \sQuote{TaskName},
    \sQuote{TaskModel}, \sQuote{ObsName} and if present
    \sQuote{ItemNumber} fields are used.} 
  \item{caf}{A string giving the CAF part of an ECDID.}
  \item{observables}{A list of \code{varDescription} objects describing
    the observable variables.}
  \item{itemColPrefix}{A a string to prepend to the front of the
    \sQuote{ItemNumber} column to generate the column names.}
  \item{appID}{A string identifier for the assessment.}
  \item{uidPrefix}{A string to prepend to a number to generate student
    identifier.} 
  \item{missingHandlers}{A list of \code{MissingCode} objects describing
    how missing values will be coded.}
  \item{demographics}{A list of \code{\link{DemographicVariableMeta}} objects.}
  \item{statistics}{A list of \code{\link{StatisticMeta}} objects.}
  \item{integerCode}{An integer or \code{NULL} describing how to code
    observable values, see \code{\link{integerCodes}}.}
}
\details{
  The most imporant factor for creating a pretest description is the
  list of tasks and observables in the assessment.  This can be derived
  from the Q-Matrix, and that is what this function does.  Other
  information about Statistics and Demographic variables is not
  derivable from the Q-Matrix and additional arguments are required to
  handle them.

  The \code{missingHandlers} argument is a collection of
  \code{MissingCode} objects describing the treatment of missing
  values.  One of the common tasks here is to recode the missing values
  on translation, so often a call to \code{recodeMissingHandlers} is in
  order to produce this.

  The \code{demographics} arguments should be a list of
  \code{\link{DemographicVariableMeta}} objects describing the
  demographic variables.

  The \code{statistics} argument should be a list of
  \code{\link{StatisticMeta}} objects describing the statistic columns.

  The \code{integerCode} argument is passed to \code{integerCodes()} to
  tell how to recode values.  A value of \code{NULL} means do not
  recode, integer values behave as defined in \code{\link{integerCodes}}.
  
}
\value{
  An object of class \code{\link{PretestDescription}}.
}
\references{
  \url{http://research.ets.org/~ralmond/StatShop/dataFormats.html}
}
\author{Russell Almond}
\section{Under Construction}{
  Probably should replaced \code{integerCodes} argument with a function
  for more flexibility.

  The architecture for this function is wrong.  We almost certainly need
  a new object of class \code{PretestDescription} to serve as an
  intermediary here and with \code{read.cpd.csv}.  This function will
  likely get a new interface when that happens.
}
\note{
  This function largely replaces the old version of
  \code{\link{xmlPretestDescription}}.  The latter is now a lightweight
  function which just produces the XML.
}
\seealso{\code{\link{xmlDemographicMeta}}, \code{\link{read.Q}},
  \code{\link{MissingCode}},
  \code{\link{recodeMissingHandlers}}, \code{\link{integerCodes}},
  \code{\link{read.cpd.csv}}
}
\examples{
  readingQ <- read.Q(paste(library(help="SSX")$path,
                           "testFiles","Q-Reading.csv",
                           sep=.Platform$file.sep))

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

  demographics <-
    list(DemographicVariableMeta("DOB","String"),
         DemographicVariableMeta("Country","String"),
         DemographicVariableMeta("Gender","Discrete",
            translationTable=c("Male"="M", "Female"="F", "NA"="")),
         DemographicVariableMeta("Age","Integer"),
         DemographicVariableMeta("GPA","Real"))

  pd <- QtoPD(readingQ,"ecd://example/Reading", observables,
                 appID="DemoReading-FormAll",
                 missingHandlers=recodeMissingHandlers(defaultMissingCodes),
                 demographics=demographics)
  pdnode <- xmlPretestDescription(pd)

}
\keyword{manip}