# The R Package equateIRT: A Tutorial

# 1 Functionalities

The equateIRT package computes:

- Direct equating coefficients (between two forms with common items).
- Chain equating coefficients (through a chain of forms with common items in pairs).
- Average (bisector) equating coefficients (between two forms connected through more than one path).
- Equated scores with true score equating and observed score equating methods.
- Standard errors of all equating coefficients and equated scores.

# 2 Data preparation

Load the package equateIRT and the data

    library("equateIRT")
    data("data2pl", package = "equateIRT")

Estimate a two parameter logistic model for 5 data sets with the R package ltm

    library("ltm")
    m1 <- ltm(data2pl[[1]] ~ z1)
    m2 <- ltm(data2pl[[2]] ~ z1)
    m3 <- ltm(data2pl[[3]] ~ z1)
    m4 <- ltm(data2pl[[4]] ~ z1)
    m5 <- ltm(data2pl[[5]] ~ z1)

Extract the item parameter estimates and the covariance matrices

    estm1 <- import.ltm(m1, display = FALSE)
    estm2 <- import.ltm(m2, display = FALSE)
    estm3 <- import.ltm(m3, display = FALSE)
    estm4 <- import.ltm(m4, display = FALSE)
    estm5 <- import.ltm(m5, display = FALSE)
    estm1$coef[1:3, ]

    ##    (Intercept)       z1
    ## I1 -0.06213808 1.076155
    ## I2 -0.03090993 1.122379
    ## I3 -0.07939847 1.091369

    estm1$var[1:3, 1:3]

    ##              [,1]         [,2]         [,3]
    ## [1,] 0.0012285184 0.0002460322 0.0002391000
    ## [2,] 0.0002460322 0.0012628923 0.0002495126
    ## [3,] 0.0002391000 0.0002495126 0.0012407430

Create a list of coefficients and covariance matrices

    estc <- list(estm1$coef, estm2$coef, estm3$coef, estm4$coef, estm5$coef)
    estv <- list(estm1$var, estm2$var, estm3$var, estm4$var, estm5$var)
    test <- paste("test", 1:5, sep = "")

Create an object of class `modIRT`

    mod2pl <- modIRT(coef = estc, var = estv, names = test, display = FALSE)
    coef(mod2pl$test1)[1:5]

    ##   Dffclt.I1   Dffclt.I2   Dffclt.I3   Dffclt.I4   Dffclt.I5
    ##  0.05774085  0.02753964  0.07275128  0.41568210 -0.00716265

The linkage plan

    lplan<-linkp(coef = estc)
    lplan

    ##      [,1] [,2] [,3] [,4] [,5]
    ## [1,]   20   10    0    0   10
    ## [2,]   10   20   10    0    0
    ## [3,]    0   10   20   10    0
    ## [4,]    0    0   10   20   10
    ## [5,]   10    0    0   10   20

A graphic of the linkage plan with package `sna`

    library(sna)
    par(mar=c(0, 0, 0, 0))
    set.seed(6)
    gplot(lplan, displaylabels = TRUE,  vertex.sides = 4, vertex.cex = 5, vertex.rot =45,  usearrows = FALSE, label.pos = 5, label.cex = 1, vertex.col = 0)

Linkage plan

# 3 Direct equating coefficients

Estimation of direct equating coefficients between Forms 1 and 2 using the mean-mean method.

NOTE: Item parameters are converted to the scale of Form 2.

    l12 <- direc(mods = mod2pl, which = c(1,2), method = "mean-mean")
    l12

    ## Direct equating coefficients
    ## Method: mean-mean
    ## Link: test1.test2

    summary(l12)

    ## Link: test1.test2
    ## Method: mean-mean
    ## Equating coefficients:
    ##   Estimate   StdErr
    ## A  1.21004 0.028981
    ## B -0.14199 0.028127

Estimation of all direct equating coefficients between forms with common items using the mean-mean method

    direclist2pl <- alldirec(mods = mod2pl, method = "mean-mean")
    direclist2pl

    ## Direct equating coefficients
    ## Method: mean-mean
    ## Links:
    ## test1.test2
    ## test1.test5
    ## test2.test1
    ## test2.test3
    ## test3.test2
    ## test3.test4
    ## test4.test3
    ## test4.test5
    ## test5.test1
    ## test5.test4

Direct equating coefficients for Forms 1 and 2

    summary(direclist2pl, link="test1.test2")

    ## Link: test1.test2
    ## Method: mean-mean
    ## Equating coefficients:
    ##   Estimate   StdErr
    ## A  1.21004 0.028981
    ## B -0.14199 0.028127

# 4 Chain equating coefficients

Estimation of all chain equating coefficients of length 4

    cec4 <- chainec(r = 4, direclist = direclist2pl)
    cec4

    ## Chain equating coefficients
    ## Method: mean-mean
    ## Paths:
    ## test4.test5.test1.test2
    ## test3.test2.test1.test5
    ## test5.test1.test2.test3
    ## test4.test3.test2.test1
    ## test5.test4.test3.test2
    ## test1.test2.test3.test4
    ## test1.test5.test4.test3
    ## test2.test3.test4.test5
    ## test2.test1.test5.test4
    ## test3.test4.test5.test1

    summary(cec4, path="test1.test2.test3.test4")

    ## Path: test1.test2.test3.test4
    ## Method: mean-mean
    ## Equating coefficients:
    ##   Estimate   StdErr
    ## A  1.25323 0.046518
    ## B -0.49789 0.038505

Chain equating coefficients for path {1, 2, 3, 4}

    summary(cec4, path="test1.test2.test3.test4")

    ## Path: test1.test2.test3.test4
    ## Method: mean-mean
    ## Equating coefficients:
    ##   Estimate   StdErr
    ## A  1.25323 0.046518
    ## B -0.49789 0.038505

Estimation of all chain equating coefficients of length 4 from Form 1 to Form 4

    cec14 <- chainec(r = 4, direclist = direclist2pl, f1 = "test1", f2 = "test4")
    cec14

    ## Chain equating coefficients
    ## Method: mean-mean
    ## Paths:
    ## test1.test2.test3.test4

    summary(cec14)

    ## Path: test1.test2.test3.test4
    ## Method: mean-mean
    ## Equating coefficients:
    ##   Estimate   StdErr
    ## A  1.25323 0.046518
    ## B -0.49789 0.038505

Estimation of chain equating coefficient for path {1, 5, 4}

    pth <- paste("test", c(1,5,4), sep = "")
    chainec154 <- chainec(direclist = direclist2pl, pths = pth)
    summary(chainec154)

    ## Path: test1.test5.test4
    ## Method: mean-mean
    ## Equating coefficients:
    ##   Estimate   StdErr
    ## A  1.15857 0.033390
    ## B -0.39971 0.033076

NOTE: Item parameters are converted to the scale of Form 4.

# 5 Average equating coefficients

Estimation of bisector equating coefficients

    ecall <- c(cec14, chainec154)
    fec <- bisectorec(ecall = ecall, weighted = TRUE, unweighted = TRUE)
    fec

    ## Bisector and weighted bisector equating coefficients
    ## Method: mean-mean
    ##
    ## Link: test1.test4
    ##   Paths:
    ##   test1.test2.test3.test4
    ##   test1.test5.test4

    summary(fec)

    ## Link: test1.test4
    ## Method: mean-mean
    ## Equating coefficients:
    ##                       Path Estimate   StdErr
    ##  A test1.test2.test3.test4  1.25323 0.046518
    ##  A       test1.test5.test4  1.15857 0.033390
    ##  A                bisector  1.20480 0.030609
    ##  A       weighted bisector  1.18885 0.029302
    ##  B test1.test2.test3.test4 -0.49789 0.038505
    ##  B       test1.test5.test4 -0.39971 0.033076
    ##  B                bisector -0.44766 0.029927
    ##  B       weighted bisector -0.43112 0.029713

Extract the equating coefficients

     eqc(fec)

    ##          link                    path        A          B
    ## 1 test1.test4 test1.test2.test3.test4 1.253235 -0.4978899
    ## 2 test1.test4       test1.test5.test4 1.158568 -0.3997148
    ## 3 test1.test4                bisector 1.204801 -0.4476611
    ## 4 test1.test4       weighted bisector 1.188853 -0.4311214

Extract item parameters of two forms being equated in the original scale and item parameters of the first form converted to the scale of the second form.

    itm(fec, bistype = "weighted")

    ##          Item       test1       test4 test1.as.test4
    ## 1   Dffclt.I1  0.05774085          NA    -0.36247602
    ## 2  Dffclt.I10  0.65469024          NA     0.34720876
    ## 3   Dffclt.I2  0.02753964          NA    -0.39838080
    ## 4  Dffclt.I21          NA -0.18987389             NA
    ## 5  Dffclt.I22          NA -0.57178646             NA
    ## 6  Dffclt.I23          NA -0.97083469             NA
    ## 7  Dffclt.I24          NA  0.28202761             NA
    ## 8  Dffclt.I25          NA  0.02635384             NA
    ## 9  Dffclt.I26          NA -0.12110226             NA
    ## 10 Dffclt.I27          NA  0.47566134             NA
    ## 11 Dffclt.I28          NA -0.01084706             NA
    ## 12 Dffclt.I29          NA -0.93620431             NA
    ## 13  Dffclt.I3  0.07275128          NA    -0.34463082
    ## 14 Dffclt.I30          NA  0.54298296             NA
    ## 15 Dffclt.I31  0.52243942          NA     0.18998205
    ## 16 Dffclt.I32  0.83132905          NA     0.55720626
    ## 17 Dffclt.I33  0.57523659          NA     0.25275010
    ## 18 Dffclt.I34 -0.34258115          NA    -0.83839982
    ## 19 Dffclt.I35  0.42869381          NA     0.07853234
    ## 20 Dffclt.I36  0.85197621          NA     0.58175268
    ## 21 Dffclt.I37  0.45623368          NA     0.11127318
    ## 22 Dffclt.I38 -0.13812533          NA    -0.59533201
    ## 23 Dffclt.I39  0.51891939          NA     0.18579726
    ## 24  Dffclt.I4  0.41568210          NA     0.06306334
    ## 25 Dffclt.I40  0.84172659          NA     0.56956741
    ## 26 Dffclt.I41          NA -1.12866114             NA
    ## 27 Dffclt.I42          NA -0.77022951             NA
    ## 28 Dffclt.I43          NA  1.08692549             NA
    ## 29 Dffclt.I44          NA  0.88814831             NA
    ## 30 Dffclt.I45          NA  0.22894864             NA
    ## 31 Dffclt.I46          NA -0.78067726             NA
    ## 32 Dffclt.I47          NA  0.13570645             NA
    ## 33 Dffclt.I48          NA -0.21808635             NA
    ## 34 Dffclt.I49          NA -0.05870549             NA
    ## 35  Dffclt.I5 -0.00716265          NA    -0.43963670
    ## 36 Dffclt.I50          NA -0.06316900             NA
    ## 37  Dffclt.I6 -0.77378858          NA    -1.35104186
    ## 38  Dffclt.I7  0.15460392          NA    -0.24732011
    ## 39  Dffclt.I8  0.33698282          NA    -0.03049849
    ## 40  Dffclt.I9 -0.18289475          NA    -0.64855625
    ## 41  Dscrmn.I1  1.07615468          NA     0.90520453
    ## 42 Dscrmn.I10  1.34017474          NA     1.12728428
    ## 43  Dscrmn.I2  1.12237949          NA     0.94408640
    ## 44 Dscrmn.I21          NA  0.96336089             NA
    ## 45 Dscrmn.I22          NA  1.01225882             NA
    ## 46 Dscrmn.I23          NA  1.05642645             NA
    ## 47 Dscrmn.I24          NA  0.87351070             NA
    ## 48 Dscrmn.I25          NA  1.06903268             NA
    ## 49 Dscrmn.I26          NA  1.10250014             NA
    ## 50 Dscrmn.I27          NA  1.04533344             NA
    ## 51 Dscrmn.I28          NA  0.93410270             NA
    ## 52 Dscrmn.I29          NA  0.93003277             NA
    ## 53  Dscrmn.I3  1.09136863          NA     0.91800171
    ## 54 Dscrmn.I30          NA  1.11202742             NA
    ## 55 Dscrmn.I31  1.48282841          NA     1.24727701
    ## 56 Dscrmn.I32  1.29985743          NA     1.09337149
    ## 57 Dscrmn.I33  1.35208875          NA     1.13730572
    ## 58 Dscrmn.I34  1.38211481          NA     1.16256205
    ## 59 Dscrmn.I35  1.27117732          NA     1.06924729
    ## 60 Dscrmn.I36  1.00818083          NA     0.84802852
    ## 61 Dscrmn.I37  1.28758500          NA     1.08304857
    ## 62 Dscrmn.I38  1.47309474          NA     1.23908957
    ## 63 Dscrmn.I39  1.34111442          NA     1.12807469
    ## 64  Dscrmn.I4  1.28072435          NA     1.07727775
    ## 65 Dscrmn.I40  1.45641060          NA     1.22505575
    ## 66 Dscrmn.I41          NA  1.03348633             NA
    ## 67 Dscrmn.I42          NA  0.96419052             NA
    ## 68 Dscrmn.I43          NA  0.99167808             NA
    ## 69 Dscrmn.I44          NA  0.95212573             NA
    ## 70 Dscrmn.I45          NA  1.13452428             NA
    ## 71 Dscrmn.I46          NA  1.18530385             NA
    ## 72 Dscrmn.I47          NA  1.04662208             NA
    ## 73 Dscrmn.I48          NA  0.94373225             NA
    ## 74 Dscrmn.I49          NA  0.80774381             NA
    ## 75  Dscrmn.I5  1.00731869          NA     0.84730333
    ## 76 Dscrmn.I50          NA  1.05234303             NA
    ## 77  Dscrmn.I6  0.94866983          NA     0.79797100
    ## 78  Dscrmn.I7  1.05732762          NA     0.88936820
    ## 79  Dscrmn.I8  1.20065598          NA     1.00992846
    ## 80  Dscrmn.I9  0.97710839          NA     0.82189202

# 6 Equated scores

Equated scores with the true score equating method

    score(fec, bistype = "weighted")

    ## The following scores are not attainable: 0

    ##         theta test4 test1.as.test4       StdErr
    ## 1  -3.2020971     1       1.015003 5.001185e-02
    ## 2  -2.4345213     2       1.954738 6.878198e-02
    ## 3  -1.9550888     3       2.892492 7.875379e-02
    ## 4  -1.5909128     4       3.840790 8.361628e-02
    ## 5  -1.2876722     5       4.804165 8.514419e-02
    ## 6  -1.0208940     6       5.784196 8.448979e-02
    ## 7  -0.7771809     7       6.780997 8.253848e-02
    ## 8  -0.5481250     8       7.793792 8.004946e-02
    ## 9  -0.3278013     9       8.821147 7.770849e-02
    ## 10 -0.1115340    10       9.861057 7.610701e-02
    ## 11  0.1048303    11      10.910935 7.564599e-02
    ## 12  0.3254635    12      11.967568 7.639989e-02
    ## 13  0.5550977    13      13.027045 7.802247e-02
    ## 14  0.7997556    14      14.084670 7.975604e-02
    ## 15  1.0679930    15      15.134866 8.052029e-02
    ## 16  1.3734260    16      16.171075 7.900041e-02
    ## 17  1.7408695    17      17.185619 7.365858e-02
    ## 18  2.2252693    18      18.169485 6.256174e-02
    ## 19  3.0011510    19      19.111786 4.257124e-02
    ## 20 42.0664330    20      20.000000 4.018669e-15

Equated scores with the observed score equating method

    score(fec, method = "OSE", bistype = "weighted")

    ##    test4 test1.as.test4     StdErr
    ## 1      0    -0.01489569 0.03615105
    ## 2      1     0.95282270 0.05477351
    ## 3      2     1.90871813 0.06629269
    ## 4      3     2.86555916 0.07346520
    ## 5      4     3.82986670 0.07760111
    ## 6      5     4.80499566 0.07951120
    ## 7      6     5.79255145 0.07985590
    ## 8      7     6.79302775 0.07916864
    ## 9      8     7.80617492 0.07787658
    ## 10     9     8.83094667 0.07644964
    ## 11    10     9.86563125 0.07533011
    ## 12    11    10.90836642 0.07475424
    ## 13    12    11.95688236 0.07472285
    ## 14    13    13.00791258 0.07499743
    ## 15    14    14.05761874 0.07509834
    ## 16    15    15.10211616 0.07433639
    ## 17    16    16.13709851 0.07186160
    ## 18    17    17.15778076 0.06678472
    ## 19    18    18.15960149 0.05830036
    ## 20    19    19.13886811 0.04575589
    ## 21    20    20.09377896 0.02876039

A comparison of equated scores obtained with 2 different chains, bisector and weighted bisector methods.

    score(chainec154, scores = 17)

    ##     theta test4 test1.as.test4     StdErr
    ## 1 1.74087    17       17.24468 0.09997669

    score(cec4, path = "test1.test2.test3.test4", scores = 17)

    ##     theta test4 test1.as.test4    StdErr
    ## 1 1.74087    17       17.06646 0.1618316

    score(fec, bistype = "unweighted", scores = 17)

    ##     theta test4 test1.as.test4     StdErr
    ## 1 1.74087    17       17.15531 0.08280613

    score(fec, bistype = "weighted", scores = 17)

    ##     theta test4 test1.as.test4     StdErr
    ## 1 1.74087    17       17.18562 0.07365858