GGUM (version 0.5)

GGUM-package: GGUM

Description

The GGUM package fits the generalized graded response model (GGUM; Roberts et al., 1996, 2000). It is based on marginal maximum likelihood (Roberts et al., 2000) to estimate the item parameters and an estimated a posteriori (EAP) method to estimate the person parameters.

The GGUM is defined by $$P(Z_i=z|\theta_n) = \frac{f(z) + f(M-z)}{\sum_{w=0}^C\left[f(w)+f(M-w)\right]}, $$

$$f(w) = exp\left\{\alpha_i\left[w(\theta_n-\delta_i)- \sum_{k=0}^w\tau_{ik}\right]\right\}, $$

where:

• The subscripts \(i\) and \(n\) identify the item and person, respectively.

• \(z=0,\ldots,C\) denotes the observed answer response.

• \(M = 2C + 1\) is the number of subjective response options minus 1.

• \(\theta_n\) is the latent trait score for person \(n\).

• \(\alpha_i\) is the item slope (discrimination).

• \(\delta_i\) is the item location.

• \(\tau_{ik}\) (\(k=1,\ldots,M\) ) are the threshold parameters.

Parameter \(\tau_{i0}\) is arbitrarily constrained to zero and the threshold parameters are constrained to symmetry around zero, that is, \(\tau_{i(C+1)}=0\) and \(\tau_{iz}=-\tau_{i(M-z+1)}\) for \(z\not= 0\).

This package produces comparable results to the ones based on the GGUM2004 program (Roberts et al., 2000; Roberts et al., 2006), for the GUM (Model 3 in GGUM2004) and the GGUM (Model 8 in GGUM2004). For those accustomed to using GGUM2004, this packages provides a useful set of functions that allow exporting data and code to GGUM2004, running GGUM2004, and retrieving the parameter estimates. Thus, if desired, one can run GGUM2004 and retrieve the results completely from within the R environment.

Versions:

• Version 0.3.1 (January 2018)
  

• Version 0.3.2 (July 2018)
  Fixed a bug related to data preprocessing (removing response patterns with all-disagree answers). Many thanks to JB Duck-Mayr for offering a fix in GitHub, and also to Michael Hermann who independently spotted the same issue (for dichotomous data).

• Version 0.4 (January 2020)
  Fixed two bugs (in Theta.EAP() and write.GGUM2004())

• Version 0.4-1 (May 2020)
  Implemented two changes in GUM.R to adapt to R 4.1 (currently R-devel) and survive CRAN's build checks.

• Version 0.4-2 (February 2021)
  Updated affiliation.

• Version 0.4-3 (October 2021)
  Implemented further changes to adapt to R 4.1, similar to what was done in Version 0.4-1.

• Version 0.5 (September 2023)
  Updated some functions to fix a bug related to identifying the class of objects.

Author

Maintainer: Jorge N. Tendeiro

Authors:

• Sebastian Castro-Alvarez

Details

Package:	GGUM
Type:	Package
Version:	0.5
Date:	2023-09-08
License:	GPL Version 2 or later

The GGUM package contains useful functions, summarized below:

• Fitting the GUM/GGUM:

  Function	Description
  GenData.GGUM	Generate data from the GUM/GGUM
  probs.GGUM	Compute model probabilities for the GGUM
  GUM	Fit the GUM
  GGUM	Fit the GGUM
  MODFIT	MODFIT for the GGUM
  Theta.EAP	Estimate thetas and their SEs (GUM, GGUM)

• Plots:

  Function	Description
  plotCRC	Plot item category response curves (CRCs)
  plotICC	Plot item characteristic curves (ICCs)
  plotIIF	Plot item information functions (IIFs)
  plotTCC	Plot test characteristic curve (TCC)
  plotTIF	Plot test information function (TIF)

• GGUM2004 interface:

  Function	Description
  export.GGUM2004	Exports data in GGUM2004 friendly format
  write.GGUM2004	Writes a command file for GGUM2004
  run.GGUM2004	Call GGUM2004 and import the estimated parameters into R
  read.item.GGUM2004	Read GGUM2004 item estimates into R
  read.person.GGUM2004	Read GGUM2004 person estimates into R

• Available methods for objects of class "GGUM":

  plot()

  print()

  summary()

References

RobertsLaughlin1996GGUM

Robertsetal2000GGUM

Robertsetal2006GGUM

See Also

Useful links:

• https://github.com/jorgetendeiro/GGUM/

Examples

if (FALSE) {
# Example 1 - Same value C across items:
# Generate data:
gen1 <- GenData.GGUM(2000, 10, 2, seed = 125)
# Fit the GGUM:
fit1 <- GGUM(gen1$data, 2)
th1  <- Theta.EAP(fit1)
# Plot the test information function:
plotTIF(fit1, th1)
# Check model fit:
MOD.res <- MODFIT(fit1)

# Example 2 - Different C across items:
# Generate data:
set.seed(1); C <- sample(3:5, 10, replace = TRUE)
I <- 10
gen2 <- GenData.GGUM(2000, I, C, seed = 125)
# Fit the GGUM:
fit2 <- GGUM(gen2$data, C)
th2  <- Theta.EAP(fit2)
# Plot item information functions for items 1 and 3:
plotIIF(fit2, th2, items = c(1, 3))

# Example 3 - Fit GGUM using GGUM2004:
# Assuming the installation directory is C:/GGUM2004, then do this:
# Export data to GGUM2004:
export.GGUM2004(gen2$data)
# Write command file:
write.GGUM2004(I, C)
# Run GGUM2004:
res.GGUM2004 <- run.GGUM2004()
}