\name{buildGMfromTables}
\alias{buildGMfromTables}
\title{Builds a graphical model from a set of parameter tables}
\description{
  This function takes a set of tables giving the parameters for a
  collection of hyper-Dirichlet distribution and builds a
  \code{\link{gmModel}} object contatining those distributions.  
}
\usage{
buildGMfromTables(id, tables, type = "SM", scaleFactor = 1,
                  addVars = NULL,
                  varRoles = ifelse(type == "SM", "SM", "Observable"),
                  taskID = character(0)) 
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{id}{A string giving an ECDID for the model (see Details).}
  \item{tables}{A named list of tables where the name represents the
    name of the dependent variable and the table gives the parameters of
    a hyper-Dirichlet distribution (see Details).}
  \item{type}{A string with the value \dQuote{SM}, \dQuote{EM}, or
    \dQuote{LM} denoting the type of model.}
  \item{scaleFactor}{A factor by which to scale the parameters of the
    hyper-Dirichlet distributions should be a scaler, or a 
    list with the same names as \code{tables} (see Details).}
  \item{addVars}{A list containing additional
    \code{\link{varDescription}} objects to add to the model (primarily
    intended for student model variable descriptions for evidence
    models).} 
  \item{varRoles}{A character vector with the same names as
    \code{tables} giving the names of the variables.}
  \item{taskID}{A string giving an ECDID of the task model to be used
    with an evidence model (see Details).  Not needed for student models.}
}
\details{
  This function tries to build up a graphical model from a collection of
  tables providing the parameters for a series of hyper-Dirichlet
  distribuitons.  Thus, it gets much of its information from the
  meta-data of the \code{tables} argument.  This should be a list whose
  names correspond to the names of the variables in the model.  Each
  element is passed to \code{\link{buildHyperDirichletDist}()} to
  construct a table.  Consequently the table should be of that format,
  with factor variables representing the parents of the distribution and
  numeric variables representing the states of the child variable.  The
  variables in the model are also derived from those tables using the
  \code{\link{getTableStates}()} function.  This assumes that the states
  are ordered in the StatShop order of \emph{highest} to \emph{lowest}
  (e.g., \sQuote{High}, \sQuote{Med}, \sQuote{Low}).

  The argument \code{id} should be a string of the general
  \code{\link{ECDID}} form, in particular, it should look like
  \samp{ecd://\var{project}/\var{caf}/\var{model}/}.  If the model being
  built is an evidence model, then \code{id} should be the link id of
  the evidence model, and \code{taskID} should be the task id of the
  corresponding task model.

  The argument \code{scaleFactor} can be used to rescale the parameter
  matrixes.  This should be a list whose names match
  \code{names(tables)}.  The values are passed to
  \code{\link{rescaleTable}()} and hence should either be a scaler or a
  vector length equal to the number of rows of the corresponding table.
  As a special case, if the value of \code{scaleFactor} is a scaler,
  then the same scaling is applied to every table.

  The function is primarily designed to be used for constructing student
  models, however, it can be used to construct evidence models with some
  additional work.  First, the \code{type} argument needs to be changed
  to \dQuote{EM} or \dQuote{LM} for evidence and link models
  respectively.  Second, the evidence model requires additional variable
  descriptions for the student model variables reference in the model.
  These are supplied in the \code{addVars} argument.  Third, the
  \code{varRoles} argument should be supplied to indicate which
  variables are observables.  This should be a named character vector
  with names corresponding to \code{names(tables)}.  Finally, the
  additional \code{taskID} argument is strongly recommended.
}
\value{
  An object of type \code{\link{gmModel}} whose variables and
  distributions correspond to the elements of \code{tables}.
}
\author{Russell Almond}
\section{Under Construction}{
  StatShop supports an alternative format for the parameter table
  involving an extra \sQuote{Sum} and \sQuote{Scale} column (see
  \code{\link{scaleTable}}).  This is not yet supported.
}
\seealso{\code{\link{gmModel}}, \code{\link{varDescription}},
  \code{\link{distribution}}, \code{\link{getTableStates}},
  \code{\link{buildHyperDirichletDist}}, \code{\link{ECDID}}
}  
\examples{
### Student Model
##Unconditional table
Skill1.ptf <- data.frame(High=.1,Medium=.3,Low=.6)
Skill2.ptf <- data.frame(High=.3,Low=.7)
Skill3.ptf <- data.frame(Skill2=c("High","Low"),
                     High=c(.8,.2),
                     Low=c(.4,.6))

##Build a student model with appropriate scaling.
sm <- buildGMfromTables("ecd://EMSMTest/TestCAF/System/",
      list(Skill1 = Skill1.ptf, Skill2 = Skill2.ptf,
           Skill3 = Skill3.ptf), scaleFactor=10)


### Evidence Model
Context.ptf <- data.frame(Familiar=30,Unfamiliar=30)
## Use the DS model to build a prior for the hyper-Dirichlet
X.ptf <- rescaleTable(
           calcDSFrame(list(Skill1=getTableStates(Skill1.ptf),
                            Context = getTableStates(Context.ptf)),
                       c("Correct","Incorrect"),
                       log(c(Skill1=1.0, Context=.5)), 0.0),
            10)

em <- buildGMfromTables("ecd://EMSMTest/TestCAF/ThreeObs/",
          list(Context = Context.ptf, X1= X.ptf, X2=X.ptf, X3=X.ptf),
          type="EM", addVars = list (sm$var$Skill1),
          varRoles = c(Context = "EM", X1= "Observable",
                       X2="Observable", X3="Observable"),
          taskID = "ecd://EMSMTest/TestCAF/ThreeItemSet/")

}
\keyword{manip}