Nothing
# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393
#' Probability of Responses to a Question Item or the Left-Cumulative Probability of Responses
#'
#' Calculates the probability of specific responses or the left-cumulative probability of responses to \code{item} conditioned on a respondent's ability (\eqn{\theta}).
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric or an integer indicating the value for \eqn{\theta_j}
#' @param item An integer indicating the index of the question item
#'
#' @return When the \code{model} slot of the \code{catObj} is \code{"ltm"}, the function \code{probability} returns a numeric vector of length one representing the probability of observing a non-zero response.
#'
#'When the \code{model} slot of the \code{catObj} is \code{"tpm"}, the function \code{probability} returns a numeric vector of length one representing the probability of observing a non-zero response.
#'
#' When the \code{model} slot of the \code{catObj} is \code{"grm"}, the function \code{probability} returns a numeric vector of length k+1, where k is the number of possible responses. The first element will always be zero and the (k+1)th element will always be one. The middle elements are the cumulative probability of observing response k or lower.
#'
#' When the \code{model} slot of the \code{catObj} is \code{"gpcm"}, the function \code{probability} returns a numeric vector of length k, where k is the number of possible responses. Each number represents the probability of observing response k.
#'
#' @details
#' For the \code{ltm} model, the probability of non-zero response for respondent \eqn{j} on item \eqn{i} is
#'
#' \deqn{Pr(y_{ij}=1|\theta_j)=\frac{\exp(a_i + b_i \theta_j)}{1+\exp(a_i + b_i \theta_j)}}
#'
#' where \eqn{\theta_j} is respondent \eqn{j} 's position on the latent scale of interest, \eqn{a_i} is item \eqn{i} 's discrimination parameter,
#' and \eqn{b_i} is item \eqn{i} 's difficulty parameter.
#'
#' For the \code{tpm} model, the probability of non-zero response for respondent \eqn{j} on item \eqn{i} is
#'
#' \deqn{Pr(y_{ij}=1|\theta_j)=c_i+(1-c_i)\frac{\exp(a_i + b_i \theta_j)}{1+\exp(a_i + b_i \theta_j)}}
#'
#' where \eqn{\theta_j} is respondent \eqn{j} 's position on the latent scale of interest, \eqn{a_i} is item \eqn{i} 's discrimination parameter,
#' \eqn{b_i} is item \eqn{i} 's difficulty parameter, and \eqn{c_i} is item \eqn{i} 's guessing parameter.
#'
#' For the \code{grm} model, the probability of a response in category \eqn{k} \strong{or lower} for respondent \eqn{j} on item \eqn{i} is
#'
#' \deqn{Pr(y_{ij} < k|\theta_j)=\frac{\exp(\alpha_{ik} - \beta_i \theta_{ij})}{1+\exp(\alpha_{ik} - \beta_i \theta_{ij})}}{Pr(y_ij < k | \theta_j) = (exp(\alpha_ik - \beta_i \theta_ij))/(1 + exp(\alpha_ik - \beta_i \theta_ij))}
#'
#' where \eqn{\theta_j} is respondent \eqn{j} 's position on the latent scale of interest, \eqn{\alpha_ik} the \eqn{k}-th element of item \eqn{i} 's difficulty parameter,
#' \eqn{\beta_i} is discrimination parameter vector for item \eqn{i}. Notice the inequality on the left side and the absence of guessing parameters.
#'
#' For the \code{gpcm} model, the probability of a response in category \eqn{k} for respondent \eqn{j} on item \eqn{i} is
#'
#' \deqn{Pr(y_{ij} = k|\theta_j)=\frac{\exp(\sum_{t=1}^k \alpha_{i} [\theta_j - (\beta_i - \tau_{it})])}
#' {\sum_{r=1}^{K_i}\exp(\sum_{t=1}^{r} \alpha_{i} [\theta_j - (\beta_i - \tau_{it}) )}}
#'
#'
#' where \eqn{\theta_j} is respondent \eqn{j} 's position on the latent scale of interest, \eqn{\alpha_i} is the discrimination parameter for item \eqn{i},
#' \eqn{\beta_i} is the difficulty parameter for item \eqn{i}, and \eqn{\tau_{it}} is the category \eqn{t} threshold parameter for item \eqn{i}, with \eqn{k = 1,...,K_i} response options
#' for item \eqn{i}. For identification purposes \eqn{\tau_{i0} = 0} and \eqn{\sum_{t=1}^1 \alpha_{i} [\theta_j - (\beta_i - \tau_{it})] = 0}. Note that when fitting the model,
#' the \eqn{\beta_i} and \eqn{\tau_{it}} are not distinct, but rather, the difficulty parameters are \eqn{\beta_{it}} = \eqn{\beta_{i}} - \eqn{\tau_{it}}.
#'
#'@examples
#'## Loading ltm Cat object
#'## Probability for Cat object of the ltm model
#'data(ltm_cat)
#'probability(ltm_cat, theta = 1, item = 1)
#'
#'## Loading tpm Cat object
#'## Probability for Cat object of the tpm model
#'probability(tpm_cat, theta = 1, item = 1)
#'
#'## Loading grm Cat object
#'## Probability for Cat object of the grm model
#'probability(grm_cat, theta = 1, item = 1)
#'
#'## Loading gpcm Cat object
#'## Probability for Cat object of the gpcm model
#'probability(gpcm_cat, theta = -3, item = 2)
#'
#' @seealso \code{\link{Cat-class}}
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @references
#' Baker, Frank B. and Seock-Ho Kim. 2004. Item Response Theory: Parameter Estimation Techniques. New York: Marcel Dekker.
#'
#' Choi, Seung W. and Richard J. Swartz. 2009. ``Comparison of CAT Item Selection Criteria for Polytomous Items." Applied Psychological Measurement 33(6):419-440.
#'
#' Muraki, Eiji. 1992. ``A generalized partial credit model: Application of an EM algorithm." ETS Research Report Series 1992(1):1-30.
#'
#' van der Linden, Wim J. 1998. ``Bayesian Item Selection Criteria for Adaptive Testing." Psychometrika 63(2):201-216.
#'
#'
#' @export
probability <- function(catObj, theta, item) {
.Call(`_catSurv_probability`, catObj, theta, item)
}
#' Likelihood of the Specified Response Set
#'
#' Calculates the likelihood of a respondent, with ability parameter \eqn{\theta}, having offered the specific set of responses stored in the \code{Cat} objects \code{answers} slot. All calculations are conditional on the item-level parameters stored in the \code{Cat} object.
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric or an integer indicating the value for \eqn{\theta}
#'
#' @return The function \code{likelihood} returns a numeric value of the likelihood of the respondent having offered the provided response profile.
#' Note that when no questions have been answered, likelihood evaluates to 1.
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @references
#' Baker, Frank B. and Seock-Ho Kim. 2004. Item Response Theory: Parameter Estimation Techniques. New York: Marcel Dekker.
#'
#' Choi, Seung W. and Richard J. Swartz. 2009. ``Comparison of CAT Item Selection Criteria for Polytomous Items." Applied Psychological Measurement 33(6):419-440.
#'
#' Muraki, Eiji. 1992. ``A generalized partial credit model: Application of an EM algorithm." ETS Research Report Series 1992(1):1-30.
#'
#' van der Linden, Wim J. 1998. ``Bayesian Item Selection Criteria for Adaptive Testing." Psychometrika 63(2):201-216.
#'
#'
#'@examples
#'## Loading ltm Cat object
#'## Likelihood for Cat object of the ltm model
#'data(ltm_cat)
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'likelihood(ltm_cat, theta = 1)
#'
#'## Loading grm Cat object
#'## Likelihood for Cat object of the grm model
#'data(grm_cat)
#'setAnswers(grm_cat) <- c(1,1,5,2,5, rep(NA, 13))
#'likelihood(grm_cat, theta = 1)
#'
#'
#'
#' @seealso \code{\link{Cat-class}}, \code{\link{probability}}
#'
#' @export
likelihood <- function(catObj, theta) {
.Call(`_catSurv_likelihood`, catObj, theta)
}
#' Evaluate the Prior Density Distribution at Position \eqn{theta}
#'
#' Calculates the density at \code{theta} of either the normal, Student's t, or uniform distribution.
#'
#' @param catObj An object of class \code{Cat}.
#' @param theta A numeric value at which to evaluate the prior
#'
#' @return The function \code{prior} returns a numeric consisting of prior value, \eqn{\pi(\theta)}, given the value \eqn{\theta}.
#'
#' @details The \code{priorName} slot of \code{Cat} object needs to be either \code{"UNIFORM"}, \code{"NORMAL"}, or \code{"STUDENT_T"}.
#'
#' When \code{priorName} slot is \code{"NORMAL"}, the first element of \code{priorParams} slot is the mean,
#' the second element is the standard deviation.
#'
#' When \code{priorName} slot is \code{"STUDENT_T"}, the first
#' element of \code{priorParams} slot is the non-centrality parameters and the second is degrees of freedom.
#'
#' When \code{priorName} slot is \code{"UNIFORM"}, the elements of the \code{priorParams} slot are the lower and upper bounds,
#' of the interval, respectively. Note that the \code{"UNIFORM"} is only applicable for the expected a posteriori (EAP) estimation method.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Prior calculation for different distributions
#'ltm_cat@priorName <- "NORMAL"
#'ltm_cat@priorParams <- c(0, 1) ## Parameters are mean and standard deviation
#'prior(ltm_cat, theta = 1)
#'
#'ltm_cat@priorName <- "STUDENT_T"
#'ltm_cat@priorParams <- c(1, 3) ## Parameters are non-centrality param and degrees of freedom
#'prior(ltm_cat, theta = 1)
#'
#'ltm_cat@priorName <- "UNIFORM"
#'ltm_cat@priorParams <- c(-1, 1) ## Parameters are lower bound and upper bound of interval
#'prior(ltm_cat, theta = 1)
#'
#'
#' @seealso
#'
#' \code{\link{Cat-class}}
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses Boost \code{C++} source libraries for the uniform and Student's t
#' distributions and calls \code{dnorm4} written in \code{C} which is identical to that
#' of \code{dnorm} in \code{R}.
#'
#'
#'
#' @export
prior <- function(catObj, theta) {
.Call(`_catSurv_prior`, catObj, theta)
}
#' The First Derivative of the Log-Likelihood
#'
#' Calculates either the first derivative of the log-likelihood or the first derivative
#' of the log-posterior evaluated at point \eqn{\theta}.
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric or an integer indicating the value for \eqn{\theta_j}
#' @param use_prior A logical indicating whether to calculate based on the log-likelihood or log-posterior
#'
#' @return The function \code{d1LL} returns a numeric of the derivative of the log-likelihood (or log-posterior) given a respondent's answer profile.
#'
#' @details
#' When the \code{usePrior} argument is \code{FALSE}, the function \code{d1LL} evaluates the first derivative of the log-likelihood at point \eqn{\theta}.
#'
#' When the \code{usePrior} argument is \code{TRUE}, the function \code{d1LL} evaluates the first derivative of the log-posterior at point \eqn{\theta}.
#'
#' If the argument \code{use_prior} is \code{TRUE}, the function \code{d1LL} must use the the normal prior distribution.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## d1LL for Cat object of the ltm model
#'d1LL(ltm_cat, theta = 1, use_prior = FALSE)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso \code{\link{Cat-class}}, \code{\link{prior}}
#'
#' @references
#' Baker, Frank B. and Seock-Ho Kim. 2004. Item Response Theory: Parameter Estimation Techniques. New York: Marcel Dekker.
#'
#' Choi, Seung W. and Richard J. Swartz. 2009. ``Comparison of CAT Item Selection Criteria for Polytomous Items." Applied Psychological Measurement 33(6):419-440.
#'
#' Muraki, Eiji. 1992. ``A generalized partial credit model: Application of an EM algorithm." ETS Research Report Series 1992(1):1-30.
#'
#' van der Linden, Wim J. 1998. ``Bayesian Item Selection Criteria for Adaptive Testing." Psychometrika 63(2):201-216.
#'
#'
#' @export
d1LL <- function(catObj, theta, use_prior) {
.Call(`_catSurv_d1LL`, catObj, theta, use_prior)
}
#' The Second Derivative of the Log-Likelihood
#'
#' Calculates either the second derivative of the log-likelihood or the second derivative
#' of the log-posterior evaluated at point \eqn{\theta}.
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric or an integer indicating the value for \eqn{\theta}
#' @param use_prior A logical indicating whether to calculate based on the log-likelihood or log-posterior
#'
#' @return The function \code{d2LL} returns a numeric of the second derivative of the log-likelihood (or log-posterior) given a respondent's answer profile.
#'
#' @details
#' When the \code{usePrior} argument is \code{FALSE}, the function \code{d2LL} evaluates the second derivative of the log-likelihood at point \eqn{\theta}.
#'
#' When the \code{usePrior} argument is \code{TRUE}, the function \code{d2LL} evaluates the second derivative of the log-posterior at point \eqn{\theta}.
#'
#' If the argument \code{use_prior} is \code{TRUE}, the function \code{d2LL} must use the the normal prior distribution.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## d2LL for Cat object of the ltm model
#'d2LL(ltm_cat, theta = 1, use_prior = FALSE)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso
#' \code{\link{Cat-class}}, \code{\link{d1LL}}, \code{\link{prior}}
#'
#' @references
#' Baker, Frank B. and Seock-Ho Kim. 2004. Item Response Theory: Parameter Estimation Techniques. New York: Marcel Dekker.
#'
#' Choi, Seung W. and Richard J. Swartz. 2009. ``Comparison of CAT Item Selection Criteria for Polytomous Items." Applied Psychological Measurement 33(6):419-440.
#'
#' Muraki, Eiji. 1992. ``A generalized partial credit model: Application of an EM algorithm." ETS Research Report Series 1992(1):1-30.
#'
#' van der Linden, Wim J. 1998. ``Bayesian Item Selection Criteria for Adaptive Testing." Psychometrika 63(2):201-216.
#'
#'
#' @export
d2LL <- function(catObj, theta, use_prior) {
.Call(`_catSurv_d2LL`, catObj, theta, use_prior)
}
#' Estimate of the Respondent's Ability Parameter
#'
#' Estimates the expected value of the ability parameter \eqn{\theta}, conditioned on the observed answers, prior, and the item parameters.
#'
#' @param catObj An object of class \code{Cat}
#'
#' @return The function \code{estimateTheta} returns a numeric consisting of the expected value of the respondent's ability parameter.
#'
#' @details
#'
#' Estimation approach is specified in \code{estimation} slot of \code{Cat} object.
#'
#' The expected a posteriori approach is used when \code{estimation} slot is \code{"EAP"}. This method involves integration. See \strong{Note} for more information.
#'
#' The modal a posteriori approach is used when \code{estimation} slot is \code{"MAP"}. This method is only available using the normal prior distribution.
#'
#' The maximum likelihood approach is used when \code{estimation} slot is \code{"MLE"}. When the likelihood is undefined,
#' the MAP or EAP method will be used, determined by what is specified in the \code{estimationDefault} slot in \code{Cat} object.
#'
#' The weighted maximum likelihood approach is used when \code{estimation} slot is \code{"WLE"}.
#' Estimating \eqn{\theta} requires root finding with the ``Brent'' method in the GNU Scientific
#' Library (GSL) with initial search interval of \code{[-5,5]}.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Set different estimation procedures and estimate ability parameter
#'setEstimation(ltm_cat) <- "EAP"
#'estimateTheta(ltm_cat)
#'
#'setEstimation(ltm_cat) <- "MAP"
#'estimateTheta(ltm_cat)
#'
#'setEstimation(ltm_cat) <- "MLE"
#'estimateTheta(ltm_cat)
#'
#'setEstimation(ltm_cat) <- "WLE"
#'estimateTheta(ltm_cat)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses adaptive quadrature methods from the GNU Scientific
#' Library (GSL) to approximate single-dimensional
#' integrals with high accuracy. The bounds of integration are determined by the
#' \code{lowerBound} and \code{upperBound} slots of the \code{Cat} object.
#'
#' @seealso \code{\link{Cat-class}}, \code{\link{estimateSE}}
#'
#' @references
#'
#' van der Linden, Wim J. 1998. "Bayesian Item Selection Criteria for Adaptive Testing." Psychometrika
#' 63(2):201-216.
#'
#' Van der Linden, Wim J., and Peter J. Pashley. 2009. "Item Selection and Ability
#' Estimation in Adaptive Testing." Elements of Adaptive Testing.
#' Springer New York, 3-30.
#'
#' @export
estimateTheta <- function(catObj) {
.Call(`_catSurv_estimateTheta`, catObj)
}
#' Observed Information
#'
#' Calculates the observed information of the likelihood of a respondent's ability \eqn{\theta} for a given \code{item}.
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric or an integer indicating the value for \eqn{\theta}
#' @param item An integer indicating the index of the question item
#'
#' @return The function \code{obsInf} returns a numeric value of the observed information of the likelihood, given \eqn{\theta}, for a given question item.
#'
#' @details The observed information is equivalent to the negative second derivative of the log-likelihood evaluated at \eqn{\theta}.
#' This function should never be called when the respondent has answered no questions as the likelihood is not defined.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Calculate observed information for different ability parameters and items
#'obsInf(ltm_cat, theta = 1, item = 10)
#'obsInf(ltm_cat, theta = 1, item = 11)
#'obsInf(ltm_cat, theta = 0, item = 10)
#'obsInf(ltm_cat, theta = 0, item = 11)
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso \code{\link{estimateTheta}}, \code{\link{expectedObsInf}}
#'
#' @export
obsInf <- function(catObj, theta, item) {
.Call(`_catSurv_obsInf`, catObj, theta, item)
}
#' Expected Observed Information
#'
#' Calculates the expected information, which is the observed information attained from a specific response set times the probability of that profile occurring.
#'
#' @param catObj An object of class \code{Cat}
#' @param item An integer indicating the index of the question item
#'
#' @return The function \code{expectedObsInf} returns a numeric value of the expected information. **Not implemented
#' for three parameter model for binary data.**
#'
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Expected observed information for different items
#'expectedObsInf(ltm_cat, item = 10)
#'expectedObsInf(ltm_cat, item = 20)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso \code{\link{estimateSE}},\code{\link{obsInf}}, \code{\link{probability}}, \code{\link{selectItem}}
#'
#' @export
expectedObsInf <- function(catObj, item) {
.Call(`_catSurv_expectedObsInf`, catObj, item)
}
#' Fisher's Information
#'
#' Calculates the expected value of the observed information of the likelihood evaluated at the input value \eqn{\theta}.
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric or an integer indicating the potential value for \eqn{\theta}
#' @param item An integer indicating the index of the question item
#'
#' @return The function \code{fisherInf} returns a numeric of the expected value of the observed information of the likelihood evaluated at the input value \eqn{\theta}.
#'
#' @details For the dichotomous case, this Fisher's information is equivalent to the observed information.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Fisher's information for different items, at ability parameter of 1
#'fisherInf(ltm_cat, theta = 1, item = 10)
#'fisherInf(ltm_cat, theta = 1, item = 20)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso \code{\link{fisherTestInfo}}, \code{\link{obsInf}}, \code{\link{selectItem}}
#'
#' @export
fisherInf <- function(catObj, theta, item) {
.Call(`_catSurv_fisherInf`, catObj, theta, item)
}
#' Fisher's Test Information
#'
#' Calculates the total information gained for a respondent for all answered items, conditioned on \eqn{\theta}.
#'
#' @param catObj An object of class \code{Cat}
#' @param theta A numeric indicating the position on the latent trait.
#'
#' @return The function \code{fisherTestInfo} returns a numeric indicating the total information gained for a respondent,
#' given a specific answer set and the current estimate of \eqn{\theta}.
#'
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Fisher's test information for answer profile
#'fisherTestInfo(ltm_cat, theta = 2)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso \code{\link{fisherInf}}
#'
#' @export
fisherTestInfo <- function(catObj, theta) {
.Call(`_catSurv_fisherTestInfo`, catObj, theta)
}
#' Standard Error of Ability Parameter Estimate
#'
#' Estimates the standard error for a respondent's ability parameter estimate, \eqn{\theta}.
#'
#' @param catObj An object of class \code{Cat}
#'
#' @return The function \code{estimateSE} returns a numeric for the standard error for \eqn{\theta}.
#'
#' @details
#'
#' The function \code{estimateSE} estimates the standard error of the ability estimate
#' given the estimation approach of the \code{Cat} object, specified in \code{estimation} slot of \code{Cat} object.
#'
#' The expected a posteriori approach is used when \code{estimation} slot is \code{"EAP"}. This method involves integration. See \strong{Note} for more information.
#'
#' The modal a posteriori approach is used when \code{estimation} slot is \code{"MAP"}. This method is only available using the normal prior distribution.
#'
#' The maximum likelihood approach is used when \code{estimation} slot is \code{"MLE"}. When the likelihood
#' of the ability estimate is undefined,
#' the MAP or EAP method will be used, determined by what is specified in the \code{estimationDefault} slot in \code{Cat} object.
#'
#' The weighted maximum likelihood approach is used when \code{estimation} slot is \code{"WLE"}.
#' Estimating \eqn{\theta} requires root finding with the ``Brent'' method in the GNU Scientific
#' Library (GSL) with initial search interval of \code{[-5,5]}.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Set different estimation procedures and calculate ability estimate and its standard error
#'setEstimation(ltm_cat) <- "EAP"
#'estimateTheta(ltm_cat)
#'estimateSE(ltm_cat)
#'
#'setEstimation(ltm_cat) <- "MAP"
#'estimateTheta(ltm_cat)
#'estimateSE(ltm_cat)
#'
#'setEstimation(ltm_cat) <- "MLE"
#'estimateTheta(ltm_cat)
#'estimateSE(ltm_cat)
#'
#'setEstimation(ltm_cat) <- "WLE"
#'estimateTheta(ltm_cat)
#'estimateSE(ltm_cat)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses adaptive quadrature methods from the GNU Scientific
#' Library (GSL) to approximate single-dimensional
#' integrals with high accuracy. The bounds of integration are determined by the
#' \code{lowerBound} and \code{upperBound} slots of the \code{Cat} object.
#'
#' @seealso \code{\link{estimateTheta}}
#'
#' @export
estimateSE <- function(catObj) {
.Call(`_catSurv_estimateSE`, catObj)
}
#' Expected Posterior Variance
#'
#' Estimates the expected posterior variance for a respondent's estimated ability parameter for an item yet to be answered based on a respondent's ability parameter estimate from the already-answered items.
#'
#' @param catObj An object of class \code{Cat}
#' @param item An integer indicating the index of the question item
#'
#' @return The function \code{expectedPV} returns a numeric value indicating a respondent's expected posterior variance for an unasked item.
#'
#'
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Estimate EPV for different unasked items
#'expectedPV(ltm_cat, item = 10)
#'expectedPV(ltm_cat, item = 20)
#'expectedPV(ltm_cat, item = 30)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#'
#' @seealso \code{\link{estimateSE}}, \code{\link{probability}}, \code{\link{selectItem}}
#'
#'
#' @export
expectedPV <- function(catObj, item) {
.Call(`_catSurv_expectedPV`, catObj, item)
}
#' Select Next Item
#'
#' Selects the next item in the question set to be administered to respondent based on the specified selection method.
#'
#' @param catObj An object of class \code{Cat}
#'
#' @return The function \code{selectItem} returns a list with three elements:
#'
#' \code{estimates}: a data frame with a row for each unasked question and three columns representing
#' the item index number, the item name, and the item value (calculated by the specified selection method),
#' and
#'
#' \code{next_item}: a numeric representing the index of the item that should be asked next.
#'
#' \code{next_item_name}: a string representing the unique identifier of the item that should be asked next.
#'
#' @details Selection approach is specified in the \code{selection} slot of the \code{Cat} object.
#'
#' The minimum expected posterior variance criterion is used when the \code{selection}
#' slot is \code{"EPV"}. This method calls \code{expectedPV} for each unasked item.
#'
#' The maximum Fisher's information criterion is used when the \code{selection}
#' slot is \code{"MFI"}. This method calls \code{fisherInf} for each unasked item.
#'
#' The maximum likelihood weighted information criterion is used when the \code{selection}
#' slot is \code{"MLWI"}. Note that when no questions have been answered, likelihood evaluates to 1. This method involves integration. See \strong{Note} for more information.
#'
#' The maximum posterior weighted information criterion is used when the \code{selection}
#' slot is \code{"MPWI"}. Note that when no questions have been answered, likelihood evaluates to 1. This method involves integration. See \strong{Note} for more information.
#'
#' The maximum expected information criterion is used when the \code{selection}
#' slot is \code{"MEI"}. This method calls \code{expectedObsInf} for each unasked item. **Not implemented
#' for three parameter model for binary data.**
#'
#' The maximum Kullback-Leibler information criterion is used when the \code{selection}
#' slot is \code{"KL"}. This method calls \code{expectedKL} for each unasked item. See \code{\link{expectedKL}} for more information.
#'
#' The maximum likelihood weighted Kullback-Leibler information criterion is used when the \code{selection}
#' slot is \code{"LKL"}. This method calls \code{likelihoodKL} for each unasked item.
#'
#' The maximum posterior weighted Kullback-Leibler information criterion is used when the \code{selection}
#' slot is \code{"PKL"}. This method calls \code{posteriorKL} for each unasked item.
#'
#' The maximum Fisher interval information criterion is used when the \code{selection}
#' slot is \code{"MFII"}. This method involves integration. See \strong{Note} for more information.
#' The bounds of integration are \eqn{\hat{\theta} \pm \delta},
#' where \eqn{\delta} is qnorm(\eqn{z}) times the square root of the Fisher test information and
#' \eqn{z} is specified in the \code{z} slot of the \code{Cat} object.
#'
#' A random number generator is used when the \code{selection}
#' slot is \code{"RANDOM"}.
#'
#' @references
#'
#' van der Linden, Wim J. 1998. "Bayesian Item Selection Criteria for Adaptive Testing." Psychometrika
#' 63(2):201-216.
#'
#' Van der Linden, Wim J., and Peter J. Pashley. 2009. "Item Selection and Ability
#' Estimation in Adaptive Testing." Elements of Adaptive Testing.
#' Springer New York, 3-30.
#'
#' Veldkamp, B.P., 2003. Item Selection in Polytomous CAT.
#' In New Developments in Psychometrics (pp. 207-214). Springer Japan.
#'
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Set different selection criterion and choose next item
#'setSelection(ltm_cat) <- "EPV"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "MFI"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "MLWI"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "MPWI"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "MEI"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "KL"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "LKL"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "PKL"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "MFII"
#'selectItem(ltm_cat)
#'
#'setSelection(ltm_cat) <- "RANDOM"
#'selectItem(ltm_cat)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses adaptive quadrature methods from the GNU Scientific
#' Library (GSL) to approximate single-dimensional
#' integrals with high accuracy. The bounds of integration are determined by the
#' \code{lowerBound} and \code{upperBound} slots of the \code{Cat} object unless otherwise noted.
#'
#' The \code{"RANDOM"} item selection criterion uses the package \code{RcppArmadillo} to randomly
#' choose the next item among unasked questions. \code{RcppArmadillo} provides an exact reproduction
#' of R's \code{sample} function that can be called from C++.
#'
#' In the rare instance that item parameters are identical, it may be that that \code{selectItem} must choose
#' between two items with the same value calculated by the selection criterion. In such an instance, \code{selectItem}
#' will choose the item with the lower question index.
#'
#'
#'
#' @seealso \code{\link{estimateTheta}}, \code{\link{expectedPV}}, \code{\link{fisherInf}}
#'
#' @export
selectItem <- function(catObj) {
.Call(`_catSurv_selectItem`, catObj)
}
#' Expected Kullback-Leibler Information
#'
#' Calculates the expected Kullback-Leibler information for an individual question item.
#'
#'
#' @param catObj An object of class \code{Cat}
#' @param item An integer indicating the index of the question item
#'
#' @details The function \code{expectedKL} calculates the expected value of the Kullback-Leibler information
#' for a specified item where the bounds of integration are \eqn{\hat{\theta} \pm \delta},
#' where \eqn{\delta} is qnorm(\eqn{z}) times the square root of the Fisher test information and
#' \eqn{z} is specified in the \code{z} slot of the \code{Cat} object. See \strong{Note} for more information on integration.
#'
#' @return The function \code{expectedKL} returns a numeric indicating the
#' expected Kullback-Leibler information
#' for the specified item, given the current answer profile and ability parameter estimate.
#'
#'
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Estimate KL for different unasked items
#'expectedKL(ltm_cat, item = 10)
#'expectedKL(ltm_cat, item = 20)
#'expectedKL(ltm_cat, item = 30)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses adaptive quadrature methods from the GNU Scientific
#' Library (GSL) to approximate single-dimensional
#' integrals with high accuracy.
#'
#' @seealso \code{\link{likelihoodKL}}, \code{\link{posteriorKL}}, \code{\link{selectItem}}
#'
#' @export
expectedKL <- function(catObj, item) {
.Call(`_catSurv_expectedKL`, catObj, item)
}
#' Expected Kullback-Leibler Information, Weighted by Likelihood
#'
#' Calculates the expected Kullback-Leibler information, weighted by likelihood, for a specified item.
#'
#'
#' @param catObj An object of class \code{Cat}
#' @param item An integer indicating the index of the question item
#'
#' @details The function \code{likelihoodKL} calculates the expected Kullback-Leibler information
#' for question \code{item}, where the proposed values of the true ability parameter are weighted by
#' the current likelihood.
#'
#'
#' This function involves integration. See \strong{Note} for more information.
#'
#'
#' @return The function \code{likelihoodKL} returns a numeric indicating the
#' expected Kullback-Leibler information weighted by the likelihood
#' for the specified item, given the current answer profile and ability parameter estimate.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Estimate EPV for different unasked items
#'likelihoodKL(ltm_cat, item = 10)
#'likelihoodKL(ltm_cat, item = 20)
#'likelihoodKL(ltm_cat, item = 30)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses adaptive quadrature methods from the GNU Scientific
#' Library (GSL) to approximate single-dimensional
#' integrals with high accuracy. The bounds of integration are determined by the
#' \code{lowerBound} and \code{upperBound} slots of the \code{Cat} object.
#'
#' @seealso \code{\link{expectedKL}}, \code{\link{posteriorKL}}, \code{\link{selectItem}}
#'
#' @export
likelihoodKL <- function(catObj, item) {
.Call(`_catSurv_likelihoodKL`, catObj, item)
}
#' Expected Kullback-Leibler Information, Weighted by the Prior
#'
#' Calculates the expected Kullback-Leibler information, weighted by likelihood and prior beliefs, for a specified item.
#'
#' @param catObj An object of class \code{Cat}
#' @param item An integer indicating the index of the question item
#'
#' @details The function \code{posteriorKL} calculates the expected Kullback-Leibler information
#' for question \code{item}, where the proposed values of the true ability parameter are weighted by
#' the prior.
#'
#' This function involves integration. See \strong{Note} for more information.
#'
#'
#' @return The function \code{posteriorKL} returns a numeric indicating the
#' expected Kullback-Leibler information weighted by the likelihood
#' for the specified item, given the current answer profile and ability parameter estimate.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## Estimate EPV for different unasked items
#'posteriorKL(ltm_cat, item = 10)
#'posteriorKL(ltm_cat, item = 20)
#'posteriorKL(ltm_cat, item = 30)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' This function uses adaptive quadrature methods from the GNU Scientific
#' Library (GSL) to approximate single-dimensional
#' integrals with high accuracy. The bounds of integration are determined by the
#' \code{lowerBound} and \code{upperBound} slots of the \code{Cat} object.
#'
#' @seealso \code{\link{expectedKL}}, \code{\link{likelihoodKL}}, \code{\link{selectItem}}
#' @export
posteriorKL <- function(catObj, item) {
.Call(`_catSurv_posteriorKL`, catObj, item)
}
#' Look Ahead to Select Next Item
#'
#' Selects the next item that would be asked for all possible response options to the question the respondent is currently answering.
#'
#' @param catObj An object of class \code{Cat}
#' @param item A numeric indicating the question item the respondent is currently answering.
#'
#' @return A function \code{lookAhead} returns a data.frame.
#' The the first column of the data frame is the possible response option to the question the respondent
#' is currently answering and the second column is the next item that should be asked given each response.
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1, rep(NA, 35))
#'
#'## What should be asked next if respondent is currently answering item 6
#'lookAhead(ltm_cat, 6)
#'
#'## Loading grm Cat object
#'data(grm_cat)
#'
#'## Store example answers
#'setAnswers(grm_cat) <- c(4,3,5,1,1, rep(NA, 13))
#'
#'## What should be asked next if respondent is currently answering item 6
#'lookAhead(grm_cat, 6)
#'
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @seealso \code{\link{selectItem}}
#'
#' @export
lookAhead <- function(catObj, item) {
.Call(`_catSurv_lookAhead`, catObj, item)
}
#' Check if Stop and/or Override Rules are Met
#'
#' Evaluates the specified stopping and/or override rules to check if respondent should be asked further questions.
#'
#' @param catObj An object of class \code{Cat}
#'
#'
#' @details The stopping rule thresholds are stored in the following \code{Cat} object slots:
#' \code{lengthThreshold}, \code{seThreshold}, \code{infoThreshold}, and \code{gainThreshold}. The override
#' thresholds are stored in the following \code{Cat} object slots: \code{lengthOverride}, \code{gainOverride}.
#' A value of \code{NA} indicates the rule will not be used in evaluating if further questions should be administered.
#' A user can specify any combination of stopping rules and/or overrides.
#'
#' \strong{Stopping Rules:}
#'
#' \code{lengthThreshold}: Number of question's answered \eqn{\geq a}
#'
#' \code{seThreshold}: \eqn{SE(\hat{\theta}) < a}
#'
#' \code{infoThreshold}: \eqn{FI < a} \eqn{\forall} remaining items
#'
#' \code{gainThreshold}: \eqn{SE(\hat{\theta}) - \sqrt{EPV} | < a} \eqn{\forall} remaining items
#'
#' \strong{Overrides:}
#'
#' \code{lengthOverride}: Number of question's answered \eqn{< a}
#'
#' \code{gainOverride}: \eqn{|SE(\hat{\theta}) - \sqrt{EPV} | \geq a} \eqn{\forall} remaining items
#'
#'
#'
#' @return The function \code{checkStopRules} returns a boolean. \code{TRUE} indicates all specified stopping rules are met
#' and no specified overrides are met. No further items should be administered. \code{FALSE} indicates at least one specified
#' stopping rule is not met, or if any specified override threshold is met. Additional items should be administered.
#'
#'
#' @examples
#'## Loading ltm Cat object
#'data(ltm_cat)
#'
#'## Store example answers
#'setAnswers(ltm_cat) <- c(1,0,1,0,1,0,0,0,1,1, rep(NA, 30))
#'
#'## Stop administering items if standard error of ability
#'## estimate is low enough
#'setSeThreshold(ltm_cat) <- .5
#'checkStopRules(ltm_cat)
#'
#'## Now stop if standard error is low enough, but only if respondent has
#'## answered 11 questions
#'setLengthOverride(ltm_cat) <- 11
#'checkStopRules(ltm_cat)
#'
#'## When respondent has answered 11 questions and standard error
#'## of ability estimate is below .5, stop administering items
#'setAnswers(ltm_cat) <- c(1,0,1,0,1,0,0,0,1,1,0, rep(NA, 29))
#'checkStopRules(ltm_cat)
#'
#'
#'@references
#'
#'Babcock, Ben, and David J. Weiss. 2009. ``Termination Criteria in Computerized Adaptive Tests: Variable-Length CATs are not Biased." Proceedings of the 2009 GMAC Conference on Computerized Adaptive Testing. Vol. 14.
#'
#'
#' @seealso \code{\link{Cat-class}}, \code{\link{estimateSE}}, \code{\link{expectedPV}}, \code{\link{fisherInf}}
#'
#' @author Haley Acevedo, Ryden Butler, Josh W. Cutler, Matt Malis, Jacob M. Montgomery,
#' Tom Wilkinson, Erin Rossiter, Min Hee Seo, Alex Weil
#'
#' @note This function is to allow users to access the internal functions of the package. During item selection, all calculations are done in compiled \code{C++} code.
#'
#' @export
checkStopRules <- function(catObj) {
.Call(`_catSurv_checkStopRules`, catObj)
}
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.