\name{PretestDescription}
\alias{PretestDescription}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{Generate an object containing layout and codebook information for
  pretest data.}
\description{
  StatShop provides a mechanism for converting between its internal
  \code{cpd.xml} format for data from an an assessment and the
  semi-standard comma separated value format.  This generates an object
  which describes the layout of the comma separated value format as well
  as any coding of factor variables.
}
\usage{
PretestDescription(appID, uidPrefix, missingHandlers = list(), demographics = list(), statistics = list(), tasks = list())
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{appID}{A string identifying the assessment.}
  \item{uidPrefix}{A string which should be prefixed to line numbers in
    the CSV file to produce examinee identifiers.}
  \item{missingHandlers}{A list of \code{\link{MissingCode}} objects
    which describe how missing values are handled in the CSV file.}
  \item{demographics}{A list of \code{\link{DemographicVariableMeta}}
    objects which describe content and coding of the demographic
    variables in the CSV file.}
  \item{statistics}{A list of \code{\link{StatisticMeta}} objects that
    describe the content and coding of the scores (reporting statistics).}
  \item{tasks}{A list of \code{\link{TaskMeta}} objects, which are
    themselves containers for \code{\link{ObservationMeta}} objects that
    describe the content and coding of the observable outcome variables
    in the CSV file.}
}
\details{
  The essential idea of the pretest description is that every
  demographic variable, statistic and observable outcome variable takes
  up one (or more if it is vector valued) columns of the comma separated
  value file.  The \code{pd.xml} file provides a list of those
  descriptions.  The \code{PretestDescription} object is an internal R
  translation of the contents of the XML layout file.

  StatShop will translate data back and forth from comma separated value
  to \code{cpd.xml} format using a \code{pd.xml} file to control the
  layout.  The \code{read.cpd.csv()} function reads the CSV file using
  the \code{PretestDescription} argument to provide layout and meta-data
  information.  

  The \code{PretestDescription} object is basically a container for lists of
  descriptions of three types of variables:  demographic variables,
  statistics (scores added to the data file when the assessment is
  scored), and observable outcome variables (which come bundled in
  tasks).  These are represented by \code{DemographicMeta},
  \code{StatisticMeta} and \code{ObservableMeta} (contained within
  \code{TaskMeta}) objects.  Any of the three categories can be empty,
  indicating that data of that type will not be recorded.  The columns
  are assumed to be in the order:  Demographics, Statistics,
  Observables.  Column numbers are computed when the
  \code{PretestDescription} object is written out to XML and are for
  human readbility only.  They are ignored by StatShop.

  Note that when StatShop converts from its internal \code{cpd.xml}
  format to CSV format, it simply drops data that do not have an entry
  in the \code{pd.xml} layout description.  This means, for example, if
  there is a typo in a task or variable name, this will result in a
  column of missing data.  It also means that \code{cpd.xml} to
  \code{pd.xml} conversion function can be used so select subsets of
  items for various purposes (e.g., split half reliability
  calculations).

  All of the various variable meta-object contain embedded coding tables
  that can be used to convert between integer and string coding for all
  of the variables.  The function \code{\link{integerCodes}()} writes
  simple coding tables that can be used for this purpose.  

  Finally, the \code{missingHandlers} field contains a list of missing
  handlers.  Generally, StatShop distinguishes between four different
  mechanism for generating missing data:
  \itemize{
    \item \emph{NA} --- Value was not calculate, or item was not presented to
    examinee, or scoring rules made answer irrelevant. 
    \item \emph{Omit} --- Task or question was presented to examinee, but
    examinee did not answer.
    \item \emph{Not Reached} --- Task or question was scheduled to be
    presented to examinee, but time ran out before examinee provided an
    answer.
    \item \emph{Invalid} --- Answer failed validation, or some other
    kind of internal error.
  }
  
  Note that the pretest description object pays attention to the
  \code{xmlCode} and \code{newval} fields of the \code{MissingCode}
  object.  These are the values used for the codes in the \code{cpd.xml}
  and CSV files respectively.

}
\value{
  A \code{PretestDescription} object.
}
\references{
%% ~put references to the literature/web site here ~
}
\author{
%%  ~~who you are~~
}
\note{
%%  ~~further notes~~
}

%% ~Make other sections like Warning with \section{Warning }{....} ~

\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
##---- Should be DIRECTLY executable !! ----
##-- ==>  Define data, use random,
##--	or do  help(data=index)  for the standard data sets.

## The function is currently defined as
function (appID, uidPrefix, missingHandlers = list(), demographics = list(), 
    statistics = list(), tasks = list()) 
{
    pd <- list(appID = appID, uidPrefix = uidPrefix, missingHandlers = missingHandlers, 
        demographics = demographics, statistics = statistics, 
        tasks = tasks)
    class(pd) <- "PretestDescription"
    pd
  }
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ ~kwd1 }
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line