Calibrate items using a 2PL, 3PL, a mixture of 2PL and 3PL models, or a 2PL model with a common discrimination parameter for all items (we call this Rasch-type). This versatile function is designed to address calibration challenges involving a substantial number of items (100-200) by grouping them into blocks of 3 to 5 items each.

```
optical(
ip,
bid = NULL,
oc = "D",
uncert = FALSE,
ipop,
imf = c(0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.45),
maxiter = rep(300, 6),
eps = rep(0.002, 6),
nnn = c(0, 50, 50, 200, 200, 200),
nsp = c(0.001, 1e-04, 1e-04, 1e-05, 1e-05, 1e-05),
sss = 0.001,
falpha = 1.08,
sdr = TRUE,
ig = 3,
ex = 0,
integ = TRUE,
show_progress = 1
)
```

- ip
Matrix containing item parameters for all items. The number of rows corresponds to the number of items, and columns represent item parameters. There are four possible configurations:

1. Rasch-type: The first two columns contain item parameters, while the first column contains 'NA' from the second item.

2. 2PL items: First two columns contain item parameters.

3. 3PL items: All three columns contain item parameters.

4. Mixed 2/3-PL: For 3-PL items, all three columns contain item parameters, while 2-PL items have NA in the third column.

- bid
Vector of integers indicating the block assignments for items. The length of bid should match the number of rows in the 'ip' matrix. Each element in the vector specifies which item belongs to which block. bid is utilized in the calibration process when dealing with more than 5 items. Note that the block should exclusively consist of Rasch-type items, 2-PL items, 3-PL items, or a combination of 2-3PL items. If blocks consist of Rasch-type, 2-PL, and 3PL items, then we need to introduce a third column with 'NA' for 2-PL and Rasch-type items in ip matrix.

- oc
optimality criterion: "D" (D-optimality, default), "I" (I-optimality with standard normal weight function), "A" (A-optimality).

- uncert
if false (default), abilities are assumed to be known; if true, handling of uncertainties of Bjermo et al. (2021) is used.

- ipop
matrix with item parameters for operational items (used if uncert=TRUE, only).

- imf
the vector of step-lengths; default c(0.005, 0.01, 0.02, 0.05, 0.1, 0.2, 0.45).

- maxiter
maximal number of iterations in each inner loop, the length of this vector defines the number of outer loops.

- eps
convergence criterion (maximum violation of eq.th.), vector with value for each iteration in the outer loop, but the same number for all iterations is recommended.

- nnn
number of new nodes added at each position in the adaptive grid, vector with value for each iteration in the outer loop (nnn [1] not used).

- nsp
node spacing between new nodes, vector with value for each iteration in the outer loop (nsp [1] is the spacing between nodes of the starting grid).

- sss
step size stopping criterion.

- falpha
factor alpha for adjusting the step size vector (should be > 1).

- sdr
stop if design repeated (flag TRUE/FALSE).

- ig
inner grid between -ig and ig.

- ex
intervals of size < ex will be removed (consolidate); if ex=0, no consolidation will be done.

- integ
if true (default), integrate() is used for computation of partial information matrices; if false, Riemann rule is used.

- show_progress
if 1 (default), no output will be printed for each iteration. If 2, the + symbols will be printed on a line for each Iteration If 3, some output of the function will be printed.

an object of class ‘optical’ is returned, which is a list with following instances:

- dd
list of directional derivatives of optimal solution for each block.

- ip
list having matrix of item paramters in each block.

- xi
list of optimal solution for each block.

- t
list of final grid of ability values which was used in each block.

- viomax
largest violation of eq.th. from final solution (if < eps, alg. has converged, otherwise not).

- h1
list of interval boundaries for optimal solution for each block.

- ht
list of Refined table of interval boundaries for optimal design with calibrated items and their corresponding probabilities for each block.

- mooiter
list for each block having monitoring iterations; information about each iteration to produce convergence plots.

- time
running time of algorithm in minutes.

- oc
list of optimality criterion ("D", "I", "A", "L") for each block.

- L
list of L-matrix (not for D-optimality) for each block.

Ul Hassan and Miller (2021). An exchange algorithm for optimal calibration of items in computerized achievement tests.*Computational Statistics and
Data Analysis, 157*: 107177.

Ul Hassan and Miller (2019). Optimal item calibration for computerized achievement tests. Psychometrika, 84, 1101-1128.

Bjermo, Fackle-Fornius, and Miller (2021). Optimizing Calibration Designs with Uncertainty in Abilities. Manuscript.

```
# Example No.1
# 2PL-model for three items with parameters (a, b) equal to (1.6, -2), (1.6, 0.5),
# and (1.6, 2) for the first, second, and third items, respectively.
# The calibration of these three items with the 2PL model is conducted in one block.
a<-c(1.6,1.6,1.6); b<-c(-2,0.5,2)
ip <-cbind(a,b)
yyy <- optical(ip)
yyy
#> Block1
#> ===================================================================
#> Table of interval boundaries for D-optimal design with items and
#> probabilities (expected proportion of examinees in this interval)
#> ===================================================================
#> Lower Upper Item Probability
#> 1 -Inf -1.0957 1 0.13662
#> 2 -1.0957 -0.3965 2 0.20925
#> 3 -0.3965 0.0705 1 0.18223
#> 4 0.0705 0.6431 3 0.21183
#> 5 0.6431 1.4099 2 0.18077
#> 6 1.4099 Inf 3 0.07929
#>
if (FALSE) {
# Example No.2
# 2PL-models for six items; parameters a=c(1.62, 0.66, 0.92, 0.90, 0.98, 1.40)
# and b=c(-0.47, -0.15, -1.71, 1.60, 0.62, -1.71), respectively.
# The calibration of these 6 items with 2PL-models is conducted in two blocks.
a<-c(1.62, 0.66,0.92,0.90,0.98,1.40)
b<-c(-0.47,-0.15,-1.71,1.60,0.62,-1.71)
ip<-cbind(a,b)
bid<-c(1,2,2,2,1,1)
yyy<-optical(ip,bid=bid)
yyy
# Example No.3
# Two-parameter logistic (2PL) models were employed for nine items, with
# parameters set as follows: a=c(1.62, 0.66, 0.92, 0.82, 0.90, 0.98, 0.36, 1.40, 0.64)
# and b=c(-0.47,-0.15, -1.71, 0.33, 1.60, 0.62, 2.84, -1.71, -1.51), respectively.
# The calibration of these nine items is conducted using 2PL models in three blocks.
ip <- cbind(c(1.62,0.66,0.92,0.82,0.90,0.98,0.36,1.40,0.64),
c(-0.47,-0.15,-1.71,0.33,1.60,0.62,2.84,-1.71,-1.51) )
bid<-c(1,2,2,3,2,1,1,3,3)
yyy <- optical(ip,bid=bid,show_progress=2)
yyy
# Example No.4
# 2PL-models with a common discrimination parameter for six items. (The model
# assumption is that six items have the same discrimination.) Parameters are
# a=(1.6, NA, NA, 1.2, NA, NA) and b=(-2, -1.5, -1, 0.5, 1, 1.5), respectively.
# 'NA' for discrimination means that the item has the same parameter as the
# preceding item. The calibration of these 6 items with 2PL-models is conducted
# in 3 blocks.
ip<-cbind(c(1.6, NA, NA, 1.2, NA, NA),c(-2, -1.5, -1, 0.5, 1, 1.5))
bid<-c(1,1,1,2,2,2)
yyy <- optical(ip,bid=bid,show_progress=2)
yyy
# Example No.5
# 3PL-models for three items; the parameters for these items are a=(1, 2, 2.5),
# b=(-1.5, 0.5, 2), and c=(0.2, 0.1, 0.05), respectively. The Calibration of
# items following 3PL-models is performed in one block.
a<-c(1, 2, 2.5); b<-c(-1.5, 0.5, 2); c<-c(0.2, 0.1, 0.05)
ip<-cbind(a,b,c)
yyy <- optical(ip,show_progress=2)
yyy
# Example No.6
# 1PL-models are applied for four items, 2PL-models to three items, 3PL-models
# to three items,and 2-3PL-models to four items. The calibration of items
# is performed in four block.
a<-c(c(1, 1.8, 1.4, 1, 2, NA, 1.7, NA, 2.5, NA, 0.8, 1.5, 2, 2.8))
b<-c(-1.5, -0.9, -0.1, -1.5, 0.5, -0.25, 1.1, 0.25, 2, 1.5, -0.5,-2, 0.5, 2)
c<-c(NA, NA, NA, 0.2, 0.1, NA, NA, NA, 0.05, NA, NA, NA, 0.1, 0.2)
ip<-cbind(a,b,c)
bid<-c(1, 2, 2, 3, 3, 1, 2, 1, 3, 1, 4, 4, 4, 4)
yyy <- optical(ip,show_progress=2)
yyy
}
```