\name{buildSMfromVar}
\alias{buildSMfromVar}
\title{Builds a student model from a variable matrix.}
\description{
  This takes a matrix giving the correlation/covaraince among a
  collection of variables and a set of marginal distributions and
  constructs a student model with the given correlations.  
}
\usage{
buildSMfromVar(id, pvecs, covariance, means = 0,
               scaleFactor = 1, start = names(pvecs)[1])
}
%- maybe also 'usage' for other objects documented here.
\arguments{
  \item{id}{A string giving an ECDID for the model (see Details).}
  \item{pvecs}{A list with naems corresponding to the variables in the
    model giving a series of probability vectors in order from highest
    state to lowest state (see Details).}
  \item{covariance}{A covariance matrix among a collection of continuous
    variables.} 
  \item{means}{The means of those variables}
  \item{scaleFactor}{A factor by which to scale the distributions.
    Should be a scaler, but could be a list with the same names as
    \code{pvecs}.}
  \item{start}{The name of the first element in ordering the parents.}
}
\details{
  This function constructs a student model following the method
  described in Almond (2006).  First it attempts to find a graphical
  structure for the model using the structure implied by the inverse
  of \code{covariance}.  The function \code{\link{buildParentList}()},
  builds the actual structure and the parameter \code{start} is passed
  to that function to determine the variable which is set
  unconditionally.

  The acutal conditional probability tables are determined by the series
  of regressions defined by \code{covariance} and the marginal
  distribuiton implied by \code{pvecs}.  The \code{pvecs} should be a
  list whose names are the names of the variables; that is except for
  order \code{colnames(covariance) == names(pvecs)}. Each element shoud
  be a named vector of probabilities in  order from the \emph{Highest}
  to the \emph{Lowest} state, e.g. \code{c(High=.2,Med=.5,Low=.3)}.  The
  function \code{\link{buildRegressions}()} and
  \code{\link{buildRegressionTables}()} are used to perform all of the work.

  The \code{scaleFactor} is used to set the effective sample size of the
  hyperDirichlet parameters.  Although in principle, any value
  accpetable to \code{\link{buildGMfromTables}} can be used, anything
  other than a scaler value is likely to cause problems.
  
  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.
}
\value{
  An object of class \code{\link{gmModel}} which contains the variables
  defined by \code{pvecs} and the distributions defined by
  \code{pvecs} and \code{convariance}.
}
\references{
  Almond, R.G. (2006, Draft) Building Bayesian Network Proficiency Models from
Factor Analysis Results.  ETS Research Memorandum (not yet submitted).
}
\author{Russell Almond}
\seealso{\code{\link{buildParentList}}, \code{\link{buildRegressions}},
  \code{\link{buildRegressionTables}}, \code{\link{buildGMfromTables}}
}
\examples{
data(MathGrades)
MG.sm <- buildSMfromVar("ecd://Whittaker/MathGrades/FiveExams/",
                        MathGrades$pvecs, MathGrades$var, MathGrades$mean,
                        scaleFactor=10, start="Algebra")
}
\keyword{manip}