\name{ECDID}
\alias{ECDID}
\alias{getECDMetaID}
\alias{getECDIDCaf}
\alias{getECDIDModel}
\alias{getECDIDtask}
\alias{makeECDID}
\title{Functions for Manipulating ECD IDs}
\description{
  An ECD ID has the general form
  \samp{ecd://\var{project}/\var{caf}/\var{model}/\var{\dots}/\var{task}.\var{version}}.
  These functions create or extract parts of the ECD ID.
}
\usage{
getECDMetaID(id)
getECDIDCaf(id)
getECDIDModel(id)
getECDIDtask(id)
makeECDID(caf, model, task=NULL, version=1)
}
\arguments{
  \item{id}{A \code{character} vector containing the ECD ID.}
  \item{caf}{The name of the \var{project} and \var{caf} in the form
    \samp{ecd://\var{project}/\var{caf}}}
  \item{model}{The name of the model as a string.  Note that if there
    are submodels (task specifications or link model priors), then
    \code{model} can contain embedded slashes.}
  \item{task}{The name of the task or \code{NULL}.  If the value is
    \code{NULL} then an ECD ID for a model object will be generated.}
  \item{version}{The version number for a task.}
}
\details{
  The ECD ID of the form
  \samp{ecd://\var{project}/\var{caf}/\var{model}/\var{\dots}/\var{task}.\var{version}}.
  is meant to uniquely define an ECD object (e.g., Student Model, Evidence
  Model, Task Model, Task, Link) within the space of all possible
  ECD projects.  The syntax is designed to mimic a URL.  ECD IDs are
  called \dfn{Task IDs} if they refer to a Task, Task Model or Task
  Specification, \dfn{Link IDs} if they refer to a Link (Model),
  Evidence Model, or Link Model Prior, and \dfn{Student Model IDs} if
  they refer to a Student Model (or Scoring Model).  Otherwise the
  syntax is identical.

  The first part of the ECD ID, \samp{ecd://\var{project}/\var{caf}}
  uniquely identifies a Conceptual Assessment Framework (CAF) within the
  space of ECD projects.  Multiple CAFs can be attached to multiple
  projects for several different reasons (sections of a test, multiple
  drafts of a model, and so forth).  From ASP's viewpoint, two objects
  which differ by either either the \var{project} or \var{caf} part of
  the ECD ID are different, so the entire initial substring is treated
  as the \code{caf}.  This is what is extracted by \code{getECDIDCaf}
  and what is used as input by \code{makeECDID}.

  The second part of the ECD ID, \var{model}, identifies the highest
  level model, a Student Model, Evidence Model or Task Model associated
  with this task.  The namespace of models is supposed to be unique
  within a CAF, thus the first three terms of the ID
  \samp{ecd://\var{project}/\var{caf}/\var{model}/}
  uniquiely identify an ECD model.  Note that by convention, ECD IDs for
  model objects end with a \sQuote{/}.

  The final parts of the ECD ID identify a particular Task in the
  assessment.  This consists of two parts, the first is a unique (within
  the scope of the CAF) name for the task, the second is a version
  number (this allows for variants of the same task to be handled in a
  reasonable way).  This part of the field is only used by Tasks and
  Links (sometimes called Link Models).  In the case of the Link Model,
  the Link ID is formed by taking the \var{task} and \var{version} part
  of the Task ID for the task and appending it to the \code{model} and
  \code{caf} part of the Evidence Model's link ID.

  The ECD framework allows for an arbitrary number of intermediate
  objects, called \dfn{Task Specifications}, between a Task Model and a
  Task. 
  While a Task Model is a meta-object, defining the relevant properities
  for a universe of tasks, the Task is a concrete object specifying one
  particular instance of the task model.  The Task Specifications are a
  heirarchicy of subsets of the universe defined by the task model, and
  task inherit values for properties from the each successive layer.
  Task Specifications are optional, but can be useful, for example to
  define \emph{Hard}, \emph{Medium}, and \emph{Easy} variants of a
  task.  If used, Task Specifications are represented by the ECD ID as a
  series of names separated by slashes in the \var{\dots} part of the Task
  ID.

  A parallel heirarchy is implied between Evidence Models and Links and
  exists with much the same notation.  An Evidence Model defines the
  parameterization for all Links that are derived from it, but the value
  of the parameters can vary from model to model.  The Evidence Model
  provides a prior distribution for the parameters of the Link.  If
  tighter priors are needed (usually corresponding to task
  specifications) \dfn{Link Model Priors} are used for this purpose.
  They behave like Task Specifications, in that they appear as the
  \var{\dots} part of the Link ID.

  ECD IDs thus support two different heirarchies, the
  \samp{Task Model > Task Specification > Task}
  heirarchy and the
  \samp{Evidence Model > Link Model Prior > Link (Model)}
  heirarchy (there is no corresponding hierarchy for Student Models).
  The immediate ancestor in the heirarchy is the value returned by
  \code{getECDMetaID}.  This literally strips the part of the ECD
  following the last slash returning the ECD ID for its predecessor in
  the hierarchy.  It is only meaningful for Task IDs and Link IDs.  Note
  that if the argument is the ID of a Task or Evidence Model, the
  returned value will be the ECD ID of the \code{caf}.
}
\value{
  A character vector whose contents depends on the function called:
  \item{getECDMetaID}{Returns the ECD ID object one step higher in the
    Task or Link hierarchy.}
  \item{getECDIDCaf}{Returns the ECD ID of the CAF, that is
    \samp{"ecd://\var{project}/\var{caf}/"}}
  \item{getECDIDModel}{Returns the name of the model part of the ID,
    that is \samp{"\var{model}"}}
  \item{getECDIDtask}{Returns the task and version number part of the
    ID, that is \samp{"\var{task}.\var{version}"}}
  \item{makeECDID}{Returns a complete ECD ID string with the given
    components, either
    \samp{"ecd://\var{project}/\var{caf}/\var{model}/"}
    if \code{task} = \code{NULL} or 
    \samp{"ecd://\var{project}/\var{caf}/\var{model}/\var{task}.\var{version}"}
    if \code{task} has any other value.}
}
\references{
  \url{http://research.ets.org/~ralmond/StatShop/dataFormats.html}
  \url{http://research.ets.org/~ralmond/StatShop/StatShop-xml/TaskNaming.txt}
  \url{http://research.ets.org/~ralmond/StatShop/StatShop-doc/TaskIDs.pdf}

} \author{Russell Almond } \examples{ 

test <- c(
  "ecd://proj/caf/model/" == makeECDID("ecd://proj/caf","model"),
  "ecd://proj/caf/model/task1.1" ==
     makeECDID("ecd://proj/caf","model","task1"),

  "ecd://proj/caf/model/spec1/spec2/" ==
     getECDMetaID("ecd://proj/caf/model/spec1/spec2/task.1"),
  "ecd://proj/caf/model/spec1/" ==
     getECDMetaID("ecd://proj/caf/model/spec1/spec2/"),
  "ecd://proj/caf/model/" ==
     getECDMetaID("ecd://proj/caf/model/spec1/"),

  "ecd://proj/caf" == getECDIDCaf("ecd://proj/caf/model/spec1/task.1"),

  "model" == getECDIDModel("ecd://proj/caf/model/spec1/task.1"),
  "model" == getECDIDModel("ecd://proj/caf/model/"),
  "model" == getECDIDModel("ecd://proj/caf/model/spec1/"),

  "task.1" == getECDIDtask("ecd://proj/caf/model/spec1/task.1"),
  "" == getECDIDtask("ecd://proj/caf/model/"),
  "" == getECDIDtask("ecd://proj/caf/model/spec1/"),

)
if (!all(test)) stop ("ECD ID self-test failed: ",test)

}
\keyword{character}% __ONLY ONE__ keyword per line