\name{addStatsForVars}
\alias{addStatsForVars}
\alias{buildStatsForVars}
\title{Creates a number of Statistic objects corresponding to Variables}
\description{
  The function \code{addStatsForVars} takes an \code{amd} file and
  modifies it by additing \code{Statistic} objects corresponding to the
  proficiency variables (in the proficiency model).

  The function \code{buildStatsForVars} takes a list of variable names
  and a statistic name, class name and model name and builds a list of
  statistic objects.
}
\usage{
addStatsForVars(amd, stats)
buildStatsForVars(varnames, statName, statClass, modelName,
                  scale = 1, offset = 0) 
}
\arguments{
  \item{amd}{An \code{amd} object we are modifying.}
  \item{stats}{A character vector whose names correspond to the
    identifiers for the statistics and whose values are the StatShop
    classes.}
  \item{varnames}{A character vector of variable names.}
  \item{statName}{A character with the identifier for the statistic.}
  \item{statClass}{A character with the StatShop class of the statistic.}
  \item{modelName}{A character with the name of the student model.}
  \item{scale}{Multiplier used for numeric statistics.}
  \item{offset}{Constant value added to statistic.}
}
\details{
  The function \code{buildStatsForVars} creates statistics with names of
  the form \dQuote{\code{statName}(\emph{var})}, where \emph{var} is
  bound to each of the values in \code{varname} in turn.  The
  \code{statClass} and \code{modelName} are used to set the \code{class}
  and \code{model} attributes of the returned objects.

  The function \code{addStatsForVars} calls \code{buildStatsForVars} to
  create statistic objects for the first student model in the \code{amd}
  object.  It uses the values of \code{stats} for the \code{statClass}
  argument and the \code{names(stats)} for the \code{statName} argument.
  The statistics are added to the \code{amd} object.
}
\value{
  For \code{buildStatsForVars}, a list of \code{Statistic} objects with
  the names of the list corresponding to the names of the statistics.

  For \code{addStatsForVars}, the \code{amd} argument modified to
  include the new statistics.
}
\references{
  \url{http://research.ets.org/~ralmond/StatShop/dataFormats.html}
}
\author{Russell Almond}
\note{
  The values in \code{statClass} (or \code{stats}) should be legal
  external names for StatShop Statistic objects.  The R code does not
  enforce this.
}
\section{Under Construction}{
  If there are multiple student models in \code{amd}, statistics are
  only generated for the first one.  This is not really well though
  through.  
}
\seealso{\code{\link{amd}}, \code{\link{Statistic}} }
\examples{

  s1 <- buildStatsForVars("Skill1","margin","Bayes Net Margin","system")
  \dontshow{
    ss1 <- s1[[1]]
    stopifnot(
      identical(ss1$name,"margin(Skill1)"),
      identical(ss1$class,"Bayes Net Margin"),
      identical(ss1$model,"system"),
      identical(ss1$reportingVars,"Skill1")
   )
  }

  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"))
  \dontshow{
   stopifnot (2*length(readingAMD$studentModels[[1]]$var) ==
              length(readingAMD$statistics))
  }
}
\keyword{manip}% at least one, from doc/KEYWORDS