# R/readin.R In irtoys: A Collection of Functions Related to Item Response Theory (IRT)

#' Read in parameter estimates
#'
#' From BILOG output, read in estimates of item parameters. Invoked
#' automatically when the model is estimated via \code{irtoys}. If that is not
#' the case, \code{file} must be a file produced with the \code{>SAVE PARm
#' file;} command in BILOG.
#'
#'
#' @param file File name
#' @return A list with three elements, \code{est}, \code{se}, \code{vcm} for the parameter
#' estimates, their standard errors, and the variance-covariance matrix per item.
#' The first two are matrices with one row per item, and three columns: [,1] item
#' discrimination \eqn{a}, [,2] item difficulty \eqn{b}, and [,3] asymptote
#' \eqn{c}. For the 1PL and 2PL models, all asymptotes are equal to 0; for the
#' 1PL, the discriminations are all equal but not necessarily equal to 1.
#' @author Ivailo Partchev
#'
#' @keywords data
nit = nrow(p)
# the covariance matrices are more trouble
vn = gsub("BLMP","COV",file)
fu = unlist(strsplit(fu, split = "\\s"))
fu = as.numeric(fu[grep("-?[0-9]+.[0-9]{6}", fu)])
m = matrix(fu, nrow=nit, byrow=TRUE)
# this extracted them all
# check which model
no_asympt = sd(m[,3])==0
no_slopes = sd(m[,1])==0
vm = lapply(1:nit,function(x){
z = matrix(0,3,3)
z[upper.tri(z,diag=TRUE)]=m[x,4:9]
di=diag(z)
z = z+t(z)
diag(z)=di
if (no_asympt) z=z[-3,-3]
if (no_slopes) z=z[2,2]
z
})
return(list(est=cbind(p[,5],p[,7],p[,11]),se=cbind(p[,6],p[,8],p[,12]),vcm=vm))
}

#'
#' From ICL output, read in estimates of item parameters. Invoked automatically
#' when the model is estimated via \code{irtoys}. If that is not the case,
#' \code{file} must be a file produced with the \code{write_item_param file}
#' command in ICL.
#'
#'
#' @param file File name
#' @return A list with three elements, \code{est}, \code{se}, \code{vcm} for the parameter
#' estimates, their standard errors, and the variance-covariance matrix per item.
#' Because ICL does not
#' compute standard errors, \code{se} and \code{vcm} will be NULL. \code{est} is a matrix with
#' one row per item, and three columns: [,1] item
#' discrimination \eqn{a}, [,2] item difficulty \eqn{b}, and [,3] asymptote
#' \eqn{c}. For the 1PL and 2PL models, all asymptotes are equal to 0; for the
#' 1PL, the discriminations are all equal but not necessarily equal to 1.
#' @author Ivailo Partchev
#'
#' @keywords models
return(list(est=matrix(scan(file),ncol=4,byrow=TRUE)[,-1],se=NULL,vcm=NULL))
}

#'
#' From ICL output, read in estimates of item parameters. \code{file} must be a
#' file produced with the \code{write_latent_dist file} command in ICL.
#' Quadrature objects are used when estimating abilities with \code{eap} and
#' for some of the scaling methods in \code{sca}.
#'
#'
#' @param file File name
#' @author Ivailo Partchev
#'
#' @keywords models
return(list(quad.points=f$V1, quad.weights=f$V2))
}

#' Read responses from a file
#'
#' Reads responses to a questionnaire from a text file
#'
#' Included for those who are too faint-hearted to write
#' into R in many other ways.
#'
#' The data values in the \code{file} must be separated with blanks.
#'
#' Responses are the empirical data used in IRT. Note that \code{irtoys} deals
#' with models for dichotomous data, and typically expects data consisting of
#' zeroes and ones, without any missing values (non-responses are considered as
#' wrong responses). In fact, there are only two commands in \code{irtoys} that
#' accept other kinds of data: \code{sco} and \code{tgf}.
#'
#' \code{read.resp} does accept missing data and values other than 0 and 1. Use
#' \code{sco} and a key to score multiple choice responses to 0/1. If you have
#' dichotomous data that contains NAs, you can use \code{sco} without a key to
#' change all NA to 0.
#'
#' @param file File name
#' @param na The symbol used to represent missing data
#' @return A matrix, typically of zeroes and ones, representing the correct or
#' wrong responses given by persons (rows) to items (columns).
#' @author Ivailo Partchev
#'
#' @keywords IO
#'
#' @examples
#'
#' \dontrun{