ker.eq: The Kernel method of test equating
In jagonzalb/SNSequate: Standard and Nonstandard Statistical Models and Methods for Test Equating

Description Usage Arguments Details Value Author(s) References See Also Examples

This function implements the kernel method of test equating as described in Holland and Thayer (1989), and Von Davier et al. (2004). Nonstandard kernels others than the gaussian are available. Associated standard error of equating are also provided.

ker.eq(scores, kert, hx=NULL, hy=NULL, degree, design, Kp=1, scores2, 
       degreeXA, degreeYA, J, K, L, wx, wy, w, 
       gapsX=NULL, gapsY=NULL, gapsA=NULL, lumpX=NULL, lumpY=NULL, lumpA=NULL,
       alpha=NULL, h.adap=NULL)

	Note that depending on the specified equating design, not all arguments are necessary as detailed below.
`scores`	If the "EG" design is specified, a two column matrix containing the raw sample frequencies coming from the two groups of scores to be equated. It is assumed that the data in the first and second columns come from tests X and Y, respectively. If the "SG" design is specified, a matrix containing the (joint) bivariate sample frequencies for X (raws) and Y (columns). If the "CB" design is specified, a two column matrix containing the observed scores of the sample taking test X first, followed by test Y. The `scores2` argument is then used for the scores of the sample taking test Y first followed by test X. If either the "NEAT_CB" or "NEAT_PSE" design is selected, a two column matrix containing the observed scores on test X (first column) and the observed scores on the anchor test A (second column). The `scores2` argument is then used for the observed scores on test Y.
`kert`	A character string giving the type of kernel to be used for continuization. Current options include "`gauss`", "`logis`", "`uniform`", "`epan`" and "`adap`" for the gaussian, logistic, uniform, Epanechnikov and Adaptative kernels, respectively
`hx`	An integer indicating the value of the bandwidth parameter to be used for kernel continuization of F(x). If not provided (Default), this value is automatically calculated (see details).
`hy`	An integer indicating the value of the bandwidth parameter to be used for kernel continuization of G(y). If not provided (Default), this value is automatically calculated (see details).
`degree`	A vector indicating the number of power moments to be fitted to the marginal distributions ("EG" design), and/or the number or cross moments to be fitted to the joint distributions (see Details).
`design`	A character string indicating the equating design (one of "EG", "SG", "CB", "NEAT_CE", "NEAT_PSE")
`Kp`	A number which acts as a weight for the second term in the combined penalization function used to obtain `h` (see details).
`scores2`	Only used for the "CB", "NEAT_CE" and "NEAT_PSE" designs. See the description of `scores`.
`degreeXA`	A vector indicating the number of power moments to be fitted to the marginal distributions X and A, and the number or cross moments to be fitted to the joint distribution (X,A) (see details). Only used for the "NEAT_CE" and "NEAT_PSE" designs.
`degreeYA`	Only used for the "NEAT_CE" and "NEAT_PSE" designs (see the description for `degreeXA`)
`J`	The number of possible X scores. Only needed for "CB", "NEAT_CB" and "NEAT_PSE" designs
`K`	The number of possible Y scores. Only needed for "CB", "NEAT_CB" and "NEAT_PSE" designs
`L`	The number of possible A scores. Needed for "NEAT_CB" and "NEAT_PSE" designs
`wx`	A number that satisfies 0<=w_x<=1 indicating the weight put on the data that is not subject to order effects. Only used for the "CB" design.
`wy`	A number that satisfies 0<=w_y<=1 indicating the weight put on the data that is not subject to order effects. Only used for the "CB" design.
`w`	A number that satisfies 0<=w<=1 indicating the weight given to population P. Only used for the "NEAT" design.
`gapsX`	A list object containing: `index` A vector of indices between 0 and J to smooth "gaps", usually ocurring at regular intervals due to scores rounded to integer values and other methodological factors. `degree` An integer indicating the maximum degree of the moments fitted by the log-linear model. Only used for the "NEAT" design.
`gapsY`	A list object containing: `index` A vector of indices between 0 and K. `degree` An integer indicating the maximum degree of the moments fitted. Only used for the "NEAT" design.
`gapsA`	A list object containing: `index` A vector of indices between 0 and L. `degree` An integer indicating the maximum degree of the moments fitted. Only used for the "NEAT" design.
`lumpX`	An integer to represent the index where an artificial "lump" is created in the marginal distribution of frecuencies for X due to recording of negative rounded formulas or any other methodological artifact.
`lumpY`	An integer to represent the index where an artificial "lump" is created in the marginal distribution of frecuencies for Y.
`lumpA`	An integer to represent the index where an artificial "lump" is created in the marginal distribution of frecuencies for A.
`alpha`	Only for Adaptative Kernel. Sensitivity parameter.
`h.adap`	Only for Adaptative Kernel. A list(hx, hy) containing bandwidths for Adaptative kernel for each Form.
`...`	Further arguments currently not used.

This is a generic function that implements the kernel method of test equating as described in Von Davier et al. (2004). Given test scores X and Y, the functions calculates

\hat{e}_Y(x)=G_{hy}^{-1}(F_{hx}(x;\hat{r}),\hat{s})

where \hat{r} and \hat{s} are estimated score probabilities obtained via loglinear smoothing (see loglin.smooth). The value of h_X and h_Y can either be specified by the user or left unspecified (default) in which case they are automatically calculated. For instance, one can specifies large values of h_X and h_Y, so that the \hat{e}_Y(x) tends to the linear equating function (see Theorem 4.5 in Von Davier et al, 2004 for more details).

An object of class ker.eq representing the kernel equating process. Generic functions such as print, and summary have methods to show the results of the equating. The results include summary statistics, equated values, standard errors of equating, and others.

The function SEED can be used to obtain standard error of equating differences (SEED) of two objects of class ker.eq. The function PREp can be used on a ker.eq object to obtain the percentage relative error measure (see Von Davier et al, 2004).

`Scores`	The possible values of xj and yk
`eqYx`	The equated values of test X in test Y scale
`eqXy`	The equated values of test Y in test X scale
`SEEYx`	The standard error of equating for equating X to Y
`SEEXy`	The standard error of equating for equating Y to X

Jorge Gonzalez B. jgonzale@mat.puc.cl

Gonzalez, J. (2014). SNSequate: Standard and Nonstandard Statistical Models and Methods for Test Equating. Journal of Statistical Software, 59(7), 1-30.

Holland, P. and Thayer, D. (1989). The kernel method of equating score distributions. (Technical Report No 89-84). Princeton, NJ: Educational Testing Service.

Holland, P., King, B. and Thayer, D. (1989). The standard error of equating for the kernel method of equating score distributions (Tech. Rep. No. 89-83). Princeton, NJ: Educational Testing Service.

Von Davier, A., Holland, P., and Thayer, D. (2004). The Kernel Method of Test Equating. New York, NY: Springer-Verlag.

loglin.smooth, SEED, PREp

#Kernel equating under the "EG" design
data(Math20EG)
mod<-ker.eq(scores=Math20EG,kert="gauss",hx=NULL,hy=NULL,degree=c(2,3),design="EG") 

summary(mod)

#Reproducing Table 7.6 in Von Davier et al, (2004)

scores<-0:20
SEEXy<-mod$SEEXy
SEEYx<-mod$SEEYx

Table7.6<-cbind(scores,SEEXy,SEEYx)
Table7.6

#Other nonstandard kernels. Table 10.3 in Von Davier (2011).

mod.logis<-ker.eq(scores=Math20EG,kert="logis",hx=NULL,hy=NULL,degree=c(2,3),design="EG") 
mod.unif<-ker.eq(scores=Math20EG,kert="unif",hx=NULL,hy=NULL,degree=c(2,3),design="EG") 
mod.gauss<-ker.eq(scores=Math20EG,kert="gauss",hx=NULL,hy=NULL,degree=c(2,3),design="EG") 

XtoY<-cbind(mod.logis$eqYx,mod.unif$eqYx,mod.gauss$eqYx)
YtoX<-cbind(mod.logis$eqXy,mod.unif$eqXy,mod.gauss$eqXy)

Table10.3<-cbind(XtoY,YtoX)
Table10.3

## Examples using Adaptive and Epanechnikov kernels
x_sim = c(1,2,3,4,5,6,7,8,9,10,11,10,9,8,7,6,5,4,3,2,1)
prob_sim = x_sim/sum(x_sim)
set.seed(1)
sim = rmultinom(1, p = prob_sim, size = 1000)

x_asimD = c(1,7,13,18,22,24,25,24,20,18,16,15,13,9,5,3,2.5,1.5,1.5,1,1)
probas_asimD = x_asimD/sum(x_asimD)
set.seed(1)
asim = rmultinom(1, p = probas_asimD, size = 1000)

scores = cbind(asim,sim)

mod.adap  = ker.eq(scores,degree=c(2,2),design="EG",kert="adap")
mod.epan  = ker.eq(scores,degree=c(2,2),design="EG",kert="epan")