# Fixed ability parameter calibration This function performs fixed ability parameter calibration (FAPC), often called Stocking's (1988) Method A, which is the maximum likelihood estimation of item parameters given ability estimates (Baker & Kim, 2004; Ban et al., 2001; Stocking, 1988). It can also be considered a special case of joint maximum likelihood estimation in which only one cycle of item parameter estimation is conducted, conditioned on the given ability estimates (Birnbaum, 1968). FAPC is a potentially useful method for calibrating pretest (or newly developed) items in computerized adaptive testing (CAT), as it enables placing their parameter estimates on the same scale as operational items. In addition, it can be used to recalibrate operational items in the item bank to evaluate potential parameter drift (Chen & Wang, 2016; Stocking, 1988). ```r est_item( x = NULL, data, score, D = 1, model = NULL, cats = NULL, item.id = NULL, fix.a.1pl = FALSE, fix.a.gpcm = FALSE, fix.g = FALSE, a.val.1pl = 1, a.val.gpcm = 1, g.val = 0.2, use.aprior = FALSE, use.bprior = FALSE, use.gprior = TRUE, aprior = list(dist = "lnorm", params = c(0, 0.5)), bprior = list(dist = "norm", params = c(0, 1)), gprior = list(dist = "beta", params = c(5, 17)), missing = NA, use.startval = FALSE, control = list(eval.max = 500, iter.max = 500), verbose = TRUE ) ``` ## Arguments - `x`: A data frame containing item metadata. This metadata is required to retrieve essential information for each item (e.g., number of score categories, IRT model type, etc.) necessary for calibration. You can create an empty item metadata frame using the function `shape_df()`. When `use.startval = TRUE`, the item parameters specified in the metadata will be used as starting values for parameter estimation. If `x = NULL`, both `model` and `cats` arguments must be specified. See `est_irt()` or `simdat()` for more details about the item metadata. Default is `NULL`. - `data`: A matrix of examinees' item responses corresponding to the items specified in the `x` argument. Rows represent examinees and columns represent items. - `score`: A numeric vector of examinees' ability estimates (theta values). The length of this vector must match the number of rows in the response data. - `D`: A scaling constant used in IRT models to make the logistic function closely approximate the normal ogive function. A value of 1.7 is commonly used for this purpose. Default is 1. - `model`: A character vector specifying the IRT model to fit each item. Available values are: * `"1PLM"`, `"2PLM"`, `"3PLM"`, `"DRM"` for dichotomous items * `"GRM"`, `"GPCM"` for polytomous items Here, `"GRM"` denotes the graded response model and `"GPCM"` the (generalized) partial credit model. Note that `"DRM"` serves as a general label covering all three dichotomous IRT models. If a single model name is provided, it is recycled for all items. This argument is only used when `x = NULL`. Default is `NULL`. - `cats`: Numeric vector specifying the number of score categories per item. For dichotomous items, this should be 2. If a single value is supplied, it will be recycled across all items. When `cats = NULL` and all models specified in the `model` argument are dichotomous (`"1PLM"`, `"2PLM"`, `"3PLM"`, or `"DRM"`), the function defaults to 2 categories per item. This argument is used only when `x = NULL`. Default is `NULL`. - `item.id`: Character vector of item identifiers. If `NULL`, IDs are generated automatically. When `fipc = TRUE`, a provided `item.id` will override any IDs present in `x`. Default is `NULL`. - `fix.a.1pl`: Logical. If `TRUE`, the slope parameters of all 1PLM items are fixed to `a.val.1pl`; otherwise, they are constrained to be equal and estimated. Default is `FALSE`. - `fix.a.gpcm`: Logical. If `TRUE`, GPCM items are calibrated as PCM with slopes fixed to `a.val.gpcm`; otherwise, each item's slope is estimated. Default is `FALSE`. - `fix.g`: Logical. If `TRUE`, all 3PLM guessing parameters are fixed to `g.val`; otherwise, each guessing parameter is estimated. Default is `FALSE`. - `a.val.1pl`: Numeric. Value to which the slope parameters of 1PLM items are fixed when `fix.a.1pl = TRUE`. Default is 1. - `a.val.gpcm`: Numeric. Value to which the slope parameters of GPCM items are fixed when `fix.a.gpcm = TRUE`. Default is 1. - `g.val`: Numeric. Value to which the guessing parameters of 3PLM items are fixed when `fix.g = TRUE`. Default is 0.2. - `use.aprior`: Logical. If `TRUE`, applies a prior distribution to all item discrimination (slope) parameters during calibration. Default is `FALSE`. - `use.bprior`: Logical. If `TRUE`, applies a prior distribution to all item difficulty (or threshold) parameters during calibration. Default is `FALSE`. - `use.gprior`: Logical. If `TRUE`, applies a prior distribution to all 3PLM guessing parameters during calibration. Default is `TRUE`. - `aprior, bprior, gprior`: A list specifying the prior distribution for all item discrimination (slope), difficulty (or threshold), guessing parameters. Three distributions are supported: Beta, Log-normal, and Normal. The list must have two elements: * `dist`: A character string, one of `"beta"`, `"lnorm"`, or `"norm"`. * `params`: A numeric vector of length two giving the distribution’s parameters. For details on each parameterization, see `stats::dbeta()`, `stats::dlnorm()`, and `stats::dnorm()`. Defaults are: * `aprior = list(dist = "lnorm", params = c(0.0, 0.5))` * `bprior = list(dist = "norm", params = c(0.0, 1.0))` * `gprior = list(dist = "beta", params = c(5, 16))` for discrimination, difficulty, and guessing parameters, respectively. - `missing`: A value indicating missing responses in the data set. Default is `NA`. - `use.startval`: Logical. If `TRUE`, the item parameters provided in the item metadata (i.e., the `x` argument) are used as starting values for item parameter estimation. Otherwise, internally generated starting values are used. Default is `FALSE`. - `control`: A list of control parameters to be passed to the optimization function `stats::nlminb()`. These parameters define settings for the item parameter estimation process, such as the maximum number of iterations. See `stats::nlminb()` for additional control options. - `verbose`: Logical. If `FALSE`, all progress messages are suppressed. Default is `TRUE`. ## Returns This function returns an object of class `est_item`. The returned object contains the following components: - **estimates**: A data frame containing both the item parameter estimates and their corresponding standard errors. - **par.est**: A data frame of item parameter estimates, structured according to the item metadata format. - **se.est**: A data frame of standard errors for the item parameter estimates, computed based on the observed information functions - **pos.par**: A data frame indicating the position of each item parameter within the estimation vector. Useful for interpreting the variance-covariance matrix. - **covariance**: A variance-covariance matrix of the item parameter estimates. - **loglikelihood**: The total log-likelihood value computed across all estimated items based on the complete response data. - **data**: A data frame of examinees' response data. - **score**: A vector of examinees' ability estimates used as fixed values during item parameter estimation. - **scale.D**: The scaling factor used in the IRT model. - **convergence**: A message indicating whether item parameter estimation successfully converged. - **nitem**: The total number of items in the response data. - **deleted.item**: Items with no response data. These items are excluded from the item parameter estimation. - **npar.est**: The total number of parameters estimated. - **n.response**: An integer vector indicating the number of valid responses for each item used in the item parameter estimation. - **TotalTime**: Total computation time in seconds. Note that you can easily extract components from the output using the `getirt()` function. ## Details In most cases, the function `est_item()` returns successfully converged item parameter estimates using its default internal starting values. However, if convergence issues arise during calibration, one possible solution is to use alternative starting values. If item parameter values are already specified in the item metadata (i.e., the `x` argument), they can be used as starting values for item parameter calibration by setting `use.startval = TRUE`. ## Examples ```r ## Import the "-prm.txt" output file from flexMIRT flex_sam <- system.file("extdata", "flexmirt_sample-prm.txt", package = "irtQ") # Extract the item metadata x <- bring.flexmirt(file = flex_sam, "par")$Group1$full_df # Modify the item metadata so that some items follow 1PLM, 2PLM, and GPCM x[c(1:3, 5), 3] <- "1PLM" x[c(1:3, 5), 4] <- 1 x[c(1:3, 5), 6] <- 0 x[c(4, 8:12), 3] <- "2PLM" x[c(4, 8:12), 6] <- 0 x[54:55, 3] <- "GPCM" # Generate examinees' abilities from N(0, 1) set.seed(23) score <- rnorm(500, mean = 0, sd = 1) # Simulate response data based on the item metadata and ability values data <- simdat(x = x, theta = score, D = 1) # 1) Estimate item parameters: constrain the slope parameters of 1PLM items # to be equal (mod1 <- est_item(x, data, score, D = 1, fix.a.1pl = FALSE, use.gprior = TRUE, gprior = list(dist = "beta", params = c(5, 17)), use.startval = FALSE )) summary(mod1) # Extract the item parameter estimates getirt(mod1, what = "par.est") # 2) Estimate item parameters: fix the slope parameters of 1PLM items to 1 (mod2 <- est_item(x, data, score, D = 1, fix.a.1pl = TRUE, a.val.1pl = 1, use.gprior = TRUE, gprior = list(dist = "beta", params = c(5, 17)), use.startval = FALSE )) summary(mod2) # Extract the standard error estimates getirt(mod2, what = "se.est") # 3) Estimate item parameters: fix the guessing parameters of 3PLM items to 0.2 (mod3 <- est_item(x, data, score, D = 1, fix.a.1pl = TRUE, fix.g = TRUE, a.val.1pl = 1, g.val = .2, use.startval = FALSE )) summary(mod3) # Extract both item parameter and standard error estimates getirt(mod2, what = "estimates") ``` ## References Baker, F. B., & Kim, S. H. (2004). **Item response theory: Parameter estimation techniques.** CRC Press. Ban, J. C., Hanson, B. A., Wang, T., Yi, Q., & Harris, D., J. (2001) A comparative study of on-line pretest item calibration/scaling methods in computerized adaptive testing. **Journal of Educational Measurement, 38**(3), 191-212. Birnbaum, A. (1968). Some latent trait models and their use in inferring an examinee's ability. In F. M. Lord & M. R. Novick (Eds.), **Statistical theories of mental test scores** (pp. 397-479). Reading, MA: Addison-Wesley. Chen, P., & Wang, C. (2016). A new online calibration method for multidimensional computerized adaptive testing. **Psychometrika, 81**(3), 674-701. Stocking, M. L. (1988). **Scale drift in on-line calibration** (Research Rep. 88-28). Princeton, NJ: ETS. ## See Also `est_irt()`, `shape_df()`, `getirt()` ## Author(s) Hwanggyu Lim hglim83@gmail.com

est_item function