\name{StatisticMeta}
\alias{StatisticMeta}
\alias{print.StatisticMeta}
\alias{toString.StatisticMeta}
\alias{StatisticMetaTypes}
\title{Description of a Statistic Column in a pretest description}
\description{
  A description of how a StatShop statistic is stored in a column or
  collection of columns in a CSV file.  This is an element in a Pretest
  Description file.
}
\usage{
StatisticMeta(name, type, column = -1, columnID = name, translationTable = NULL, levels = character())
print.StatisticMeta(x, ...)                               
toString.StatisticMeta(x, ...)
StatisticMetaTypes
}
\arguments{
  \item{name}{String giving the identifier for the statistic.}
  \item{type}{String giving the type of the Statistic, should be one of
    the values in \code{StatisticMetaTypes}}
  \item{column}{Column number for Statistic.  See Details.}
  \item{columnID}{Column name for Statistic.  See Details.}
  \item{translationTable}{A translation type describing how
    \sQuote{Discrete} variables are coded.}
  \item{levels}{A character vector giving the names of the states in the
    order they appear in the CSV file for \sQuote{Probability}
    statistics.} 
  \item{x}{Dummy argument to \code{print} or \code{toString}.}
  \item{\dots}{Additional arguments to \code{print} or \code{toString}.}
}
\details{
  This object is a parallel to the \code{StatisticMeta} element in a
  Pretest description.  As a result, the main use of this class is to
  build a list of column descriptions to pass to
  \code{\link{xmlPretestDescription}}, to generate \code{pd.xml} files.

  Currently, StatShop supports four kinds of statistics:  \sQuote{Real},
  \sQuote{Integer}, \sQuote{Discrete}, and \sQuote{Probability}.  The
  \sQuote{Real} and \sQuote{Integer} types are self-explanatory.

  The \sQuote{Discrete} type represents a statistic which can take on a
  finite set of values (e.g., the mode of a discrete random variable).
  As such, it generally requires the \code{translationTable} argument to
  be non-null.  The translation table should be a named character vector
  where the \code{names(translationTable)} are the possible states of the
  statistic and the values are the values used to code them.  The function
  be used with \code{\link{integerCodes}} generates one possible value
  for this table.

  The \sQuote{Probability} type represents a series of consecutive
  columns providing the probability for each of the states described in
  the \code{levels} argument (usually the \code{levels}) from a discrete
  probability.  In this case, the \code{levels} argument must be
  supplied and the \code{column} and \code{columnID} arguments are
  interpreted specially.  The \code{column} argument gives the column
  number for the first column (corresponding to \code{levels[1]}) and
  columns for other levels are presumed to occur consecutively.  The
  \code{columnID} is treated like a prefix and the name of the level is
  appended to generate the column name, with no separator character.
}
\value{
  For \sQuote{StatisticMeta} An object of type \sQuote{StatisticMeta}
  with fields as in the arguments section.
}
\note{
  The \code{column} field is purely advisory.  In practice, the
  \code{\link{xmlPretestDescription}} code relies on the order of the
  elements to generate official column numbers.  As a special case, the
  default value of \code{-1} indicates that this value should be
  autogenerated by \code{\link{nextPDColumn}}.
}
\references{
  \url{http://research.ets.org/~ralmond/StatShop/dataFormats.html}
}
\author{Russell Almond}
\seealso{\code{\link{xmlDemographicMeta}},
  \code{\link{xmlPretestDescription}}, \code{\link{xmlStatisticMeta}},
  \code{\link{integerCodes}}, \code{\link{read.cpd.csv}},
  \code{\link{nextPDColumn}}
}
\examples{
  realstat <- StatisticMeta("mean(Skill1)","Real",columnID="Mean.Skill1")
  discstat <- StatisticMeta("mode(Skill1)","Discrete",columnID="Mode.Skill1", 
     translationTable = integerCodes(c("High","Medium","Low"),NULL))
  probstat <- StatisticMeta("margin(Skill1)","Probability",
     columnID="p.Skill1.", levels = c("High","Medium","Low"))
}
\keyword{manip}