# =============================================================================
# Additional file 3. Analysis code
#
# What can a national medical examination diagnose? A cross-sectional
# cognitive diagnostic modelling study from Brazil
#
# This script reproduces the analyses reported in the article from public data:
#   (1) the ENAMED 2025 microdata released by INEP (final-year students of the
#       Enade component), available at
#       https://www.gov.br/inep/pt-br/acesso-a-informacao/dados-abertos/microdados/enamed
#       Files used: microdados_enade_2025_arq3.txt (response vectors) and
#                   microdados2025_parametros_itens.txt (item parameters and the
#                   correspondence between booklet-1 and booklet-2 item numbers);
#   (2) Additional file 1 (Additional_file_1_Q-matrices.xlsx), which holds the ten
#       Q-matrices, one per worksheet.
# Section 1 builds the aligned response matrix from the INEP files. The same
# matrix is provided as Additional file 4 (Additional_file_4_aligned_responses.csv);
# if that file is present in the working folder it is read directly and the INEP
# files are not needed.
#
# Requirements: R (>= 4.3) and the packages GDINA (2.13.2 was used), pROC and
# readxl. Install with: install.packages(c("GDINA", "pROC", "readxl"))
#
# Usage: set the three paths below and run the whole script, for example with
#   Rscript Additional_file_3_gdina_analysis.R
# Results are written to the folder given in OUT_DIR. Fitting all ten
# specifications with limited-information fit statistics takes several hours
# on a desktop computer (modelfit() is the slowest step); set RUN_MODELFIT to
# FALSE for a quicker run without M2, RMSEA2 and SRMSR.
# =============================================================================

MICRODATA_DIR <- "microdados_enamed_2025/DADOS"        # folder with the INEP .txt files
AF4_FILE      <- "Additional_file_4_aligned_responses.csv"  # Additional file 4 (optional)
Q_FILE        <- "Additional_file_1_Q-matrices.xlsx"   # Additional file 1
OUT_DIR       <- "results"
RUN_MODELFIT  <- TRUE

suppressPackageStartupMessages({
  library(GDINA)
  library(pROC)
  library(readxl)
})
dir.create(OUT_DIR, showWarnings = FALSE, recursive = TRUE)

# -----------------------------------------------------------------------------
# 1. Scored responses aligned to the booklet-1 item order
# -----------------------------------------------------------------------------
# DS_VT_ACE_OBJ holds one character per item (1 = correct, 0 = incorrect,
# 6 = annulled item), in the order of the booklet the examinee answered
# (CO_CADERNO = 1 or 2). The parameter file lists the 93 items that were not
# annulled, with their positions in both booklets; ITEM_MANTIDO = 1 marks the
# 90 items retained by INEP in calibration (the other three had non-positive
# biserial correlations). Booklet-2 responses are re-ordered into the booklet-1
# sequence with NU_ITEM_PROVA_1 and NU_ITEM_PROVA_2.
prepare_responses <- function(arq3_file, param_file) {
  d <- read.table(arq3_file, sep = ";", header = TRUE, quote = "\"", comment.char = "",
                  colClasses = "character", na.strings = "", fill = TRUE)
  d <- d[d$TP_PR_GER == "555", ]                      # present with a valid result
  par <- read.table(param_file, sep = ";", header = TRUE, na.strings = c("", "."))
  keep <- par[par$ITEM_MANTIDO == 1, ]
  keep <- keep[order(keep$NU_ITEM_PROVA_1), ]
  v <- do.call(rbind, strsplit(d$DS_VT_ACE_OBJ, ""))    # examinees x 100, booklet order
  stopifnot(ncol(v) == 100, all(d$CO_CADERNO %in% c("1", "2")))
  x <- matrix(NA_character_, nrow(v), nrow(keep))
  b1 <- d$CO_CADERNO == "1"; b2 <- d$CO_CADERNO == "2"
  x[b1, ] <- v[b1, keep$NU_ITEM_PROVA_1, drop = FALSE]
  x[b2, ] <- v[b2, keep$NU_ITEM_PROVA_2, drop = FALSE]
  stopifnot(all(x %in% c("0", "1")))
  X <- matrix(as.integer(x == "1"), nrow(x), ncol(x),
              dimnames = list(NULL, paste0("Q", keep$NU_ITEM_PROVA_1)))
  list(X = X, booklet = as.integer(d$CO_CADERNO))
}

if (file.exists(AF4_FILE)) {
  af4 <- read.csv(AF4_FILE)
  booklet <- af4$booklet; X <- as.matrix(af4[, -1])
} else {
  resp <- prepare_responses(file.path(MICRODATA_DIR, "microdados_enade_2025_arq3.txt"),
                            file.path(MICRODATA_DIR, "microdados2025_parametros_itens.txt"))
  X <- resp$X; booklet <- resp$booklet
  write.csv(data.frame(booklet = booklet, X), file.path(OUT_DIR, AF4_FILE), row.names = FALSE, quote = FALSE)
}
cat("Examinees:", nrow(X), "(39,256 in the article); items:", ncol(X), "\n")

# -----------------------------------------------------------------------------
# 2. Descriptive statistics and booklet check
# -----------------------------------------------------------------------------
score <- rowSums(X)
p <- colMeans(X); k <- ncol(X)
kr20 <- k / (k - 1) * (1 - sum(p * (1 - p)) / var(score))
rit <- sapply(seq_len(k), function(j) cor(X[, j], score - X[, j]))   # corrected item-total r
descriptives <- c(N = nrow(X), n_booklet1 = sum(booklet == 1), n_booklet2 = sum(booklet == 2),
                  mean = mean(score), sd = sd(score), median = median(score), min = min(score), max = max(score),
                  KR20 = kr20, p_min = min(p), p_max = max(p), rit_min = min(rit), rit_max = max(rit),
                  rit_median = median(rit),
                  r_p_booklets = cor(colMeans(X[booklet == 1, ]), colMeans(X[booklet == 2, ])),
                  mean_booklet1 = mean(score[booklet == 1]), mean_booklet2 = mean(score[booklet == 2]))
write.csv(data.frame(statistic = names(descriptives), value = descriptives),
          file.path(OUT_DIR, "descriptives.csv"), row.names = FALSE)
print(round(descriptives, 3))

# -----------------------------------------------------------------------------
# 3. Q-matrices (Additional file 1: columns Item, Booklet 2, Topic, attributes)
# -----------------------------------------------------------------------------
SPECS <- c("Tasks original", "Tasks revised", "Content original", "Content revised",
           "Settings original", "Settings revised", "D1 Life cycle", "D2 Detailed life cycle",
           "D3 Sex or gender", "D4 Integrated")
read_Q <- function(sheet) {
  q <- as.data.frame(read_excel(Q_FILE, sheet = sheet))
  Q <- as.matrix(q[, -(1:3)]); storage.mode(Q) <- "integer"; rownames(Q) <- q$Item
  stopifnot(identical(rownames(Q), colnames(X)))
  Q
}

# -----------------------------------------------------------------------------
# 4. Model fitting and summaries for one specification
# -----------------------------------------------------------------------------
analyse_spec <- function(Q, run_modelfit = RUN_MODELFIT) {
  K <- ncol(Q); res <- list(K = K, attributes = colnames(Q))
  fit <- GDINA(X, Q, model = "GDINA", att.dist = "saturated", mono.constraint = TRUE, verbose = 0)
  res$fit <- fit
  res$npar <- npar(fit)$`No. of parameters`
  res$logLik <- as.numeric(logLik(fit)); res$AIC <- AIC(fit); res$BIC <- BIC(fit)
  if (run_modelfit) {
    mf <- modelfit(fit)
    res$M2 <- mf$M2; res$M2_df <- mf$M2.df; res$RMSEA2 <- mf$RMSEA2; res$SRMSR <- mf$SRMSR
  }
  ca <- CA(fit); res$CA_pattern <- ca$tau; res$CA_attribute <- ca$tau_k
  res$itemfit <- try(itemfit(fit), silent = TRUE)
  # mastery classification (marginal posterior probability >= 0.5)
  mp <- personparm(fit, what = "mp"); prof <- (mp >= 0.5) * 1L
  res$profiles_matrix <- prof
  res$prevalence <- colMeans(prof)
  res$prevalence_by_booklet <- rbind(booklet1 = colMeans(prof[booklet == 1, , drop = FALSE]),
                                     booklet2 = colMeans(prof[booklet == 2, , drop = FALSE]))
  res$profiles <- sort(table(apply(prof, 1, paste, collapse = "")), decreasing = TRUE)
  # latent (phi) correlations from the estimated joint attribute distribution
  pc <- extract(fit, "posterior.prob")[1, ]; pat <- attributepattern(K)
  m <- colSums(pat * pc); cv <- t(pat) %*% (pat * pc) - m %o% m
  res$phi <- cv / sqrt(diag(cv) %o% diag(cv)); dimnames(res$phi) <- list(colnames(Q), colnames(Q))
  # empirical Q-matrix validation (PVAF, cut-off 0.95), used only as auxiliary information
  qv <- try(Qval(fit, method = "PVAF", eps = 0.95), silent = TRUE)
  if (!inherits(qv, "try-error")) {
    sq <- extract(qv, "sug.Q"); res$PVAF_suggested_Q <- sq
    res$PVAF_cells_changed <- mean(sq != Q); res$PVAF_items_changed <- mean(rowSums(sq != Q) > 0)
  }
  # DINA comparison (only informative when some items require more than one attribute)
  if (max(rowSums(Q)) > 1) {
    fd <- GDINA(X, Q, model = "DINA", att.dist = "saturated", verbose = 0)
    res$DINA <- c(npar = npar(fd)$`No. of parameters`, logLik = as.numeric(logLik(fd)), BIC = BIC(fd))
  }
  # raw score as a predictor of full mastery
  full <- as.integer(rowSums(prof) == K)
  ro <- roc(full, score, quiet = TRUE, direction = "<")
  ci <- as.numeric(ci.auc(ro, method = "delong"))
  res$full_mastery <- mean(full)
  res$AUC <- c(lower = ci[1], AUC = ci[2], upper = ci[3])
  res$roc <- ro
  cuts <- data.frame(cut = 30:85)
  cuts$sensitivity <- sapply(cuts$cut, function(c) mean(score[full == 1] >= c))
  cuts$specificity <- sapply(cuts$cut, function(c) mean(score[full == 0] < c))
  cuts$accuracy    <- sapply(cuts$cut, function(c) mean((score >= c) == (full == 1)))
  cuts$youden      <- cuts$sensitivity + cuts$specificity - 1
  res$cuts <- cuts
  res$youden_cut   <- cuts[which.max(cuts$youden), ]
  res$accuracy_cut <- cuts[which.max(cuts$accuracy), ]
  res$score_by_n_mastered <- tapply(score, rowSums(prof), quantile, probs = c(.05, .25, .5, .75, .95))
  res
}

# -----------------------------------------------------------------------------
# 5. Run all specifications and write summary tables
# -----------------------------------------------------------------------------
results <- list()
for (s in SPECS) {
  cat("Fitting:", s, "\n")
  results[[s]] <- analyse_spec(read_Q(s))
  saveRDS(results[[s]], file.path(OUT_DIR, paste0(gsub(" ", "_", s), ".rds")))
}
na_if_null <- function(x) if (is.null(x)) NA else x
fit_table <- do.call(rbind, lapply(SPECS, function(s) {
  r <- results[[s]]
  data.frame(specification = s, K = r$K, npar = r$npar, BIC = r$BIC,
             RMSEA2 = na_if_null(r$RMSEA2), SRMSR = na_if_null(r$SRMSR),
             CA_pattern = r$CA_pattern, CA_attribute_min = min(r$CA_attribute),
             CA_attribute_max = max(r$CA_attribute),
             DINA_BIC = if (is.null(r$DINA)) NA else r$DINA[["BIC"]],
             PVAF_cells_changed_pct = 100 * na_if_null(r$PVAF_cells_changed),
             full_mastery_pct = 100 * r$full_mastery, AUC = r$AUC[["AUC"]],
             AUC_lower = r$AUC[["lower"]], AUC_upper = r$AUC[["upper"]],
             youden_cut = r$youden_cut$cut, accuracy_cut = r$accuracy_cut$cut,
             max_booklet_difference_pp = 100 * max(abs(r$prevalence_by_booklet[1, ] - r$prevalence_by_booklet[2, ])))
}))
fit_table$delta_BIC <- fit_table$BIC - min(fit_table$BIC)
write.csv(fit_table, file.path(OUT_DIR, "fit_and_roc_summary.csv"), row.names = FALSE)
prev_table <- do.call(rbind, lapply(SPECS, function(s) {
  r <- results[[s]]
  data.frame(specification = s, attribute = r$attributes, prevalence = r$prevalence,
             classification_accuracy = r$CA_attribute)
}))
write.csv(prev_table, file.path(OUT_DIR, "attribute_prevalence.csv"), row.names = FALSE)
print(fit_table, digits = 4)
