\name{xmlTaskList}
\alias{xmlTaskList}
\title{Writes a StatShop Task Data Description (tdd.xml) file based on a Q-Matrix}
\description{
  Writes out a \code{tdd.xml} file containing details about the tasks
  and anchors used in an assessment form based on a Qmatrix.  This is an
  XML file which can be used with StatShop for calibration, data
  generation and similar activities.
}
\usage{
xmlTaskList(Qmat, caf, anchors = character(0), toplevel = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{Qmat}{A data frame containing a Q-Matrix (see
    \code{\link{read.Q}}.} 
  \item{caf}{A string giving the CAF part of an ECDID.}
  \item{anchors}{A character vector mapping a name of an anchor to a
    proficiency variable.  See details.}
  \item{toplevel}{A logical flag, if true the appropriate XML namespace
    and schema attributes are added to the top level node.}
}
\details{
  The Task Description Data (\code{tdd.xml}) is an auxiliary file sent
  to StatShop along with the Assessment Model Description
  (\code{amd.xml}).  The TDD file is meant to provide information about
  specific tasks used in a particular form of the assessment, as opposed
  to the general description about task models found the in the AMD.
  The TDD file is used by both the StatShop calibrator and data
  generator.

  The TDD file is basically a manefest of tasks, although it includes
  placeholders for task model variables (currently unused).  It also
  contains information about \dQuote{scale anchors}.

  \dfn{Scale anchors} are a collection of observables used to define the
  scale and location of a proficiency variable.  These should all have
  DiBello--Samejima type distributions and they are defined so that the
  sum of the difficulty and log discrimination parameters across the
  anchor set is zero.  The column \code{Qmat$Anchors} is used to mark
  the which anchor set (if any) the observable belongs to.  The argument
  \code{anchors} should be a mapping of the form
  \code{\emph{anchorName}=\code{profVarName}} where \emph{anchorName} is
  a string found in \code{Qmat$Anchors} and \emph{profVarName} is the
  name of a proficiency variable.

  The function \code{xmlTaskList} produces produces an object of type
  \code{XMLNode} which can be written with \code{xmlWrite}.  As this is
  the top level XML object, the constant \code{tdd.prefix} gives the
  namespace prefix and the constants \code{tdd.namespace} and
  \code{tdd.schemaLocation} provide details about the schema location.
}
\value{
  An object of type \code{XMLNode} containing a \code{<TaskList>}
  element. 
}
\references{
  \url{http://research.ets.org/~ralmond/StatShop/dataFormats.html}
}
\author{Russell Almond}
\section{Under Construction}{
  The architecture currently goes directly from the Q-Matrix to the
  XML.  We should probably add an intermediate TaskList object which can
  be manipulated.  The interface for this function will likely change if
  that happens.
}
\seealso{
  \code{\link{tdd.namespace}}, \code{\link{xmlWrite}},
  \code{\link{tdd.prefix}}, \code{\link{tdd.schemaLocation}},
  \code{\link[XML]{XMLNode}}, \code{\link{xmlSimpleTaskList}} for an
    alternative mechanism.
}
\examples{
  readingQ <- read.Q(paste(library(help="SSX")$path,
                           "testFiles","Q-Reading.csv",
                           sep=.Platform$file.sep))

  anchorsA <- c("WordA"="WordMeaning", "SpecA"="SpecificInformation",
              "ConnectA"="ReadingConnectInfo", "SynthA"="SynthesizeOrganize")
  tlnode <- xmlTaskList(readingQ,"ecd://example/Reading",anchorsA)
\dontrun{
  saveXML(tlnode,"Task/ReadingAllForms.tdd.xml")
}
}
\keyword{interface}