# ============================================================
# PARTE I - ANÁLISE DE ITENS PELA TCT E PELA TRI
# Modelo logístico de dois parâmetros (2PL)
# ============================================================

# OBJETIVO:
# Realizar uma análise psicométrica de uma avaliação,
# utilizando a Teoria Clássica dos Testes (TCT) e a
# Teoria de Resposta ao Item (TRI).
#
# Estrutura da base:
# - Linhas: estudantes
# - Colunas: itens
# - Valores: 0 = erro e 1 = acerto


# ============================================================
# 1. INSTALAÇÃO E CARREGAMENTO DOS PACOTES
# ============================================================

# Instalar os pacotes caso ainda não estejam instalados
#pacotes <- c("mirt", "psych", "openxlsx")
#instalar <- pacotes[!pacotes %in% installed.packages()[, "Package"]]
#if (length(instalar) > 0) {
#  install.packages(instalar)
#}

# Carregar os pacotes
library(mirt)
library(psych)
library(openxlsx)


# ============================================================
# 2. PREPARAÇÃO DA BASE DE DADOS
# ============================================================

# Substitua "dados" pelo nome da sua base, caso necessário.
# A base deve conter somente as respostas dos estudantes
# aos itens da avaliação.
# Exemplo de estrutura:
# Estudante | Q1 | Q2 | Q3 | Q4 | ... | Q14
# 1         |  1 |  0 |  1 |  1 | ... |  0
# 2         |  1 |  1 |  0 |  1 | ... |  1

# Ler a base de dados
dados <- readxl::read_excel("dados.xlsx")

# Conferir a estrutura da base
str(dados)

# Conferir as primeiras observações
head(dados)

# Verificar a quantidade de estudantes e itens
cat("Número de estudantes:", nrow(dados), "\n")
cat("Número de itens:", ncol(dados), "\n")

# Garantir que as respostas sejam numéricas
dados <- as.data.frame(
  lapply(dados, as.numeric)
)

# Verificar se existem respostas diferentes de 0, 1 ou NA
if (!all(unlist(dados) %in% c(0, 1, NA))) {
  stop("A base deve conter somente respostas 0, 1 ou NA.")
}

# Verificar a quantidade de respostas ausentes
cat("Total de respostas ausentes:", sum(is.na(dados)), "\n")

# Verificar a distribuição de respostas por item
distribuicao_respostas <- lapply(
  dados,
  table,
  useNA = "ifany"
)

print(distribuicao_respostas)


# ============================================================
# 3. TCT - ESCORE TOTAL DOS ESTUDANTES
# ============================================================

# Na TCT, o escore total é obtido pela soma das respostas
# corretas de cada estudante.
# Calcular o escore total
escore_TCT <- rowSums(dados, na.rm = FALSE)

# Criar tabela com os escores
resultado_estudantes <- data.frame(
  Estudante = seq_len(nrow(dados)),
  Escore_TCT = escore_TCT
)

# Estatísticas descritivas do escore
estatisticas_TCT <- data.frame(
  Media = mean(escore_TCT, na.rm = TRUE),
  Mediana = median(escore_TCT, na.rm = TRUE),
  Desvio_Padrao = sd(escore_TCT, na.rm = TRUE),
  Minimo = min(escore_TCT, na.rm = TRUE),
  Maximo = max(escore_TCT, na.rm = TRUE)
)

print(estatisticas_TCT)

# Histograma dos escores
hist(
  escore_TCT,
  main = "Distribuição dos escores - TCT",
  xlab = "Escore total",
  ylab = "Frequência",
  col = "lightblue",
  border = "white"
)


# ============================================================
# 4. TCT - DIFICULDADE DOS ITENS
# ============================================================

# Na TCT, a dificuldade do item é calculada pela proporção
# de estudantes que acertaram determinada questão.
# Quanto maior a proporção de acertos, mais fácil é o item.
# Calcular a proporção de acertos
dificuldade_TCT <- colMeans(dados, na.rm = TRUE)

# Criar tabela de dificuldade
analise_dificuldade <- data.frame(
  Item = colnames(dados),
  Proporcao_Acertos = as.numeric(dificuldade_TCT)
)

# Classificação ilustrativa da dificuldade
analise_dificuldade$Classificacao <- cut(
  analise_dificuldade$Proporcao_Acertos,
  breaks = c(-Inf, 0.30, 0.70, Inf),
  labels = c(
    "Difícil",
    "Intermediário",
    "Fácil"
  ),
  right = FALSE
)

print(analise_dificuldade)

# Gráfico da proporção de acertos
barplot(
  analise_dificuldade$Proporcao_Acertos,
  names.arg = analise_dificuldade$Item,
  main = "Dificuldade dos itens - TCT",
  xlab = "Itens",
  ylab = "Proporção de acertos",
  ylim = c(0, 1),
  col = "lightblue"
)


# ============================================================
# 5. TCT - DISCRIMINAÇÃO DOS ITENS
# ============================================================

# A discriminação será analisada por meio da correlação
# item-total corrigida (r.drop).
# Esse indicador mede a associação entre a resposta de um item
# e o escore total calculado sem considerar o próprio item.
# Calcular o Alfa de Cronbach e as estatísticas dos itens
alpha_resultado <- psych::alpha(
  dados,
  check.keys = FALSE
)

# Extrair as estatísticas dos itens
estatisticas_itens <- alpha_resultado$item.stats

# Extrair a correlação item-total corrigida
discriminacao_TCT <- estatisticas_itens$r.drop

# Criar tabela de discriminação
# Os nomes dos itens são obtidos diretamente da base,
# evitando o problema de names() retornar NULL.
analise_discriminacao <- data.frame(
  Item = colnames(dados),
  Discriminacao = as.numeric(discriminacao_TCT)
)

# Classificar a discriminação
analise_discriminacao$Classificacao <- cut(
  analise_discriminacao$Discriminacao,
  breaks = c(-Inf, 0.20, 0.30, Inf),
  labels = c(
    "Baixa associação",
    "Associação moderada",
    "Boa associação"
  ),
  right = FALSE
)

print(analise_discriminacao)

# Gráfico de discriminação
barplot(
  analise_discriminacao$Discriminacao,
  names.arg = analise_discriminacao$Item,
  main = "Discriminação dos itens - TCT",
  xlab = "Itens",
  ylab = "Correlação item-total corrigida",
  col = "lightgreen"
)


# ============================================================
# 6. TCT - CONFIABILIDADE DO TESTE
# ============================================================

# O Alfa de Cronbach avalia a consistência interna do conjunto
# de itens.
# Para itens dicotômicos (0 e 1), o Alfa de Cronbach equivale
# numericamente ao coeficiente KR-20.
# Extrair o Alfa de Cronbach
alpha_cronbach <- alpha_resultado$total$raw_alpha
cat("Alfa de Cronbach:", alpha_cronbach, "\n")

# Verificar o Alfa de Cronbach caso cada item seja excluído
analise_alpha <- data.frame(
  Item = rownames(alpha_resultado$alpha.drop),
  Alpha_sem_item = alpha_resultado$alpha.drop$raw_alpha
)

print(analise_alpha)

# Interpretação:
# Se a exclusão de determinado item aumentar consideravelmente
# o Alfa, vale investigar o comportamento desse item.
#
# Entretanto, a exclusão não deve ser decidida apenas pelo Alfa.


# ============================================================
# 7. TRI - AJUSTE DO MODELO LOGÍSTICO DE DOIS PARÂMETROS (2PL)
# ============================================================

# O modelo 2PL considera dois parâmetros para cada item:
#
# a = discriminação
# b = dificuldade
#
# A probabilidade de acerto depende da proficiência do estudante
# e dos parâmetros do item.
#
# O modelo utilizado é:
#
# P(Xij = 1 | theta_j) =
# 1 / [1 + exp(-a_i(theta_j - b_i))]
#
# O ajuste será realizado pelo método da Máxima
# Verossimilhança Marginal (MML), utilizando o algoritmo EM.
mod <- mirt(
  data = dados,
  model = 1,
  itemtype = "2PL",
  method = "EM"
)

# Visualizar resumo do modelo
summary(mod)


# ============================================================
# 8. TRI - ESTIMAÇÃO DOS PARÂMETROS DOS ITENS
# ============================================================

# Extrair os parâmetros na parametrização tradicional da TRI.
parametros_TRI <- coef(
  mod,
  IRTpars = TRUE,
  simplify = TRUE
)

# Extrair os parâmetros dos itens
itens_TRI <- as.data.frame(
  parametros_TRI$items
)

# Conferir os resultados
print(itens_TRI)

# Criar tabela com os parâmetros de discriminação e dificuldade
analise_TRI <- data.frame(
  Item = rownames(itens_TRI),
  Discriminacao_a = itens_TRI$a,
  Dificuldade_b = itens_TRI$b
)

print(analise_TRI)

# Interpretação:
#
# Parâmetro a:
# Quanto maior o valor, maior a discriminação do item.
#
# Parâmetro b:
# Quanto maior o valor, maior a dificuldade do item.
#
# O parâmetro b representa a posição do item na escala
# de proficiência, e não a proporção de acertos da TCT.


# ============================================================
# 9. TRI - AJUSTE DOS ITENS
# ============================================================

# Analisar o ajuste dos itens ao modelo 2PL.
ajuste_itens <- itemfit(mod)
print(ajuste_itens)

# O itemfit apresenta estatísticas para investigar se os itens
# apresentam comportamento compatível com o modelo ajustado.
#
# Valores-p baixos podem indicar desajuste, mas a interpretação
# deve considerar o tamanho da amostra e a multiplicidade
# de testes.


# ============================================================
# 10. TRI - AJUSTE GLOBAL DO MODELO
# ============================================================

# Estatística M2 para avaliação do ajuste global.
ajuste_global <- tryCatch(
  M2(mod),
  error = function(e) {
    message("Não foi possível calcular M2: ", e$message)
    NULL
  }
)

print(ajuste_global)


# ============================================================
# 11. TRI - DEPENDÊNCIA LOCAL ENTRE OS ITENS
# ============================================================

# O Q3 de Yen permite investigar dependência local.
#
# Espera-se que, após considerar a proficiência, os itens
# apresentem independência local.
residuos_Q3 <- residuals(
  mod,
  type = "Q3"
)

print(residuos_Q3)

# Os valores de Q3 devem ser analisados em conjunto.
# Correlações residuais elevadas podem indicar dependência
# local entre determinados itens.


# ============================================================
# 12. TRI - CURVAS CARACTERÍSTICAS DOS ITENS
# ============================================================

# A Curva Característica do Item (CCI) representa a relação
# entre a proficiência e a probabilidade de acerto.
# Gerar as curvas características dos itens
plot(
  mod,
  type = "trace",
  facet_items = TRUE
)

# Interpretação:
#
# Eixo X: proficiência (theta)
# Eixo Y: probabilidade de acerto
#
# A inclinação da curva está relacionada ao parâmetro a.
# O posicionamento horizontal está relacionado ao parâmetro b.


# ============================================================
# 13. TRI - CURVA DE INFORMAÇÃO DOS ITENS E DO TESTE
# ============================================================

# A informação representa a precisão com que o teste
# mede a proficiência em diferentes pontos da escala.
# Informação dos itens
plot(
  mod,
  type = "infotrace"
)

# Informação total do teste
plot(
  mod,
  type = "info"
)

# Interpretação:
#
# Quanto maior a informação, menor tende a ser o erro-padrão
# da medida naquela região da escala.
#
# Um teste pode apresentar maior precisão para estudantes
# com proficiência intermediária e menor precisão nas
# extremidades da escala.


# ============================================================
# 14. TRI - ESTIMAÇÃO DAS PROFICIÊNCIAS DOS ESTUDANTES
# ============================================================

# Estimar as proficiências utilizando o método EAP
# (Expected A Posteriori).
# Também serão calculados os erros-padrão das estimativas.
prof_estudantes <- fscores(
  mod,
  method = "EAP",
  full.scores.SE = TRUE
)

# Transformar em data frame
prof_estudantes <- as.data.frame(
  prof_estudantes
)

# Conferir os resultados
head(prof_estudantes)

# Criar tabela com estudantes, proficiência e erro-padrão
resultado_TRI <- data.frame(
  Estudante = seq_len(nrow(dados)),
  Proficiência = prof_estudantes$F1,
  Erro_Padrao = prof_estudantes$SE_F1
)

print(head(resultado_TRI))

# Estatísticas descritivas das proficiências
estatisticas_prof <- data.frame(
  Media = mean(resultado_TRI$Proficiência, na.rm = TRUE),
  Mediana = median(resultado_TRI$Proficiência, na.rm = TRUE),
  Desvio_Padrao = sd(resultado_TRI$Proficiência, na.rm = TRUE),
  Minimo = min(resultado_TRI$Proficiência, na.rm = TRUE),
  Maximo = max(resultado_TRI$Proficiência, na.rm = TRUE)
)

print(estatisticas_prof)

# Histograma das proficiências
hist(
  resultado_TRI$Proficiência,
  main = "Distribuição das proficiências - TRI",
  xlab = "Proficiência (theta)",
  ylab = "Frequência",
  col = "lightgreen",
  border = "white"
)


# ============================================================
# 15. COMPARAÇÃO ENTRE TCT E TRI
# ============================================================

# Comparar os escores totais da TCT com as proficiências
# estimadas pela TRI.
comparacao <- data.frame(
  Estudante = seq_len(nrow(dados)),
  Escore_TCT = escore_TCT,
  Proficiência_TRI = resultado_TRI$Proficiência
)

# Correlação entre os dois indicadores
correlacao_TCT_TRI <- cor(
  comparacao$Escore_TCT,
  comparacao$Proficiência_TRI,
  use = "complete.obs",
  method = "pearson"
)

cat(
  "Correlação entre TCT e TRI:",
  correlacao_TCT_TRI,
  "\n"
)

# Gráfico de dispersão
plot(
  comparacao$Escore_TCT,
  comparacao$Proficiência_TRI,
  main = "Comparação entre TCT e TRI",
  xlab = "Escore total - TCT",
  ylab = "Proficiência - TRI",
  pch = 19
)

abline(
  lm(
    Proficiência_TRI ~ Escore_TCT,
    data = comparacao
  ),
  lwd = 2
)


# ============================================================
# 16. COMPARAÇÃO DA DIFICULDADE DOS ITENS: TCT E TRI
# ============================================================

# Na TCT:
# Quanto maior a proporção de acertos, mais fácil o item.
#
# Na TRI:
# Quanto maior o parâmetro b, mais difícil o item.
#
# Portanto, espera-se uma associação negativa entre
# a proporção de acertos (TCT) e o parâmetro b (TRI).
comparacao_dificuldade <- merge(
  analise_dificuldade,
  analise_TRI,
  by = "Item"
)

# Correlação entre a proporção de acertos e o parâmetro b
correlacao_dificuldade <- cor(
  comparacao_dificuldade$Proporcao_Acertos,
  comparacao_dificuldade$Dificuldade_b,
  use = "complete.obs",
  method = "pearson"
)

cat(
  "Correlação entre dificuldade TCT e TRI:",
  correlacao_dificuldade,
  "\n"
)

# Gráfico de dispersão
plot(
  comparacao_dificuldade$Proporcao_Acertos,
  comparacao_dificuldade$Dificuldade_b,
  main = "Dificuldade dos itens: TCT x TRI",
  xlab = "Proporção de acertos - TCT",
  ylab = "Parâmetro b - TRI",
  pch = 19
)

abline(
  lm(
    Dificuldade_b ~ Proporcao_Acertos,
    data = comparacao_dificuldade
  ),
  lwd = 2
)


# ============================================================
# 17. COMPARAÇÃO DA DISCRIMINAÇÃO DOS ITENS: TCT E TRI
# ============================================================

# Na TCT:
# Utilizamos a correlação item-total corrigida.
#
# Na TRI:
# Utilizamos o parâmetro a.
#
# As duas medidas não são equivalentes, mas ambas estão
# relacionadas à capacidade de diferenciação dos estudantes.
comparacao_discriminacao <- merge(
  analise_discriminacao,
  analise_TRI,
  by = "Item"
)

# Correlação entre os indicadores de discriminação
correlacao_discriminacao <- cor(
  comparacao_discriminacao$Discriminacao,
  comparacao_discriminacao$Discriminacao_a,
  use = "complete.obs",
  method = "pearson"
)

cat(
  "Correlação entre discriminação TCT e TRI:",
  correlacao_discriminacao,
  "\n"
)

# Gráfico de dispersão
plot(
  comparacao_discriminacao$Discriminacao,
  comparacao_discriminacao$Discriminacao_a,
  main = "Discriminação dos itens: TCT x TRI",
  xlab = "Correlação item-total corrigida - TCT",
  ylab = "Parâmetro a - TRI",
  pch = 19
)

abline(
  lm(
    Discriminacao_a ~ Discriminacao,
    data = comparacao_discriminacao
  ),
  lwd = 2
)


# ============================================================
# 18. EXPORTAÇÃO DOS RESULTADOS PARA EXCEL
# ============================================================

# Organizar os resultados em uma lista de planilhas.
resultados_exportacao <- list(
  "Escores_TCT" = resultado_estudantes,
  "Estatisticas_TCT" = estatisticas_TCT,
  "Dificuldade_TCT" = analise_dificuldade,
  "Discriminacao_TCT" = analise_discriminacao,
  "Confiabilidade_TCT" = data.frame(
    Alfa_Cronbach = alpha_cronbach
  ),
  "Alfa_sem_item" = analise_alpha,
  "Parametros_TRI" = analise_TRI,
  "Ajuste_itens_TRI" = as.data.frame(ajuste_itens),
  "Profiencias_TRI" = resultado_TRI,
  "Estatisticas_prof" = estatisticas_prof,
  "Comparacao_TCT_TRI" = comparacao,
  "Comparacao_dificuldade" = comparacao_dificuldade,
  "Comparacao_discriminacao" = comparacao_discriminacao
)

# Criar arquivo Excel com todas as planilhas
write.xlsx(
  resultados_exportacao,
  file = "Resultados_Analise_TCT_TRI.xlsx",
  overwrite = TRUE
)

cat(
  "Análises concluídas! Arquivo Excel exportado com sucesso.\n"
)


# ============================================================
# FIM DA PARTE I
# ============================================================



# ############################################################
# ############################################################


# ============================================================
# PARTE II - ANÁLISE PSICOMÉTRICA - TEORIA DE RESPOSTA AO ITEM
# Modelo logístico de três parâmetros (3PL)
# ============================================================

# OBJETIVO:
# Realizar uma análise psicométrica de uma avaliação educacional
# utilizando o modelo logístico de três parâmetros da TRI.
#
# Estrutura da base:
# - Linhas: estudantes
# - Colunas: itens
# - Valores: 0 = erro e 1 = acerto
#
# Parâmetros do modelo:
# a = discriminação
# b = dificuldade
# c = probabilidade de acerto casual
#
# Método de estimação:
# Máxima Verossimilhança Marginal (MML), por meio do algoritmo EM.
#
# Pacote utilizado: mirt


# ============================================================
# 1. INSTALAÇÃO E CARREGAMENTO DOS PACOTES
# ============================================================

pacotes <- c("mirt", "psych", "openxlsx")

instalar <- pacotes[
  !pacotes %in% installed.packages()[, "Package"]
]

if (length(instalar) > 0) {
  install.packages(instalar)
}

library(mirt)
library(psych)
library(openxlsx)


# ============================================================
# 2. PREPARAÇÃO DA BASE DE DADOS
# ============================================================

# A base deve conter somente as respostas dos estudantes
# aos itens da avaliação.
#
# IMPORTANTE:
# Caso exista uma coluna de identificação dos estudantes,
# ela deverá ser retirada antes desta etapa.
# Conferir a estrutura da base
str(dados)

# Visualizar as primeiras observações
head(dados)

# Transformar as respostas em formato numérico
dados <- as.data.frame(
  lapply(dados, as.numeric)
)

# Verificar a quantidade de estudantes e itens
cat("Número de estudantes:", nrow(dados), "\n")
cat("Número de itens:", ncol(dados), "\n")

# Verificar se existem respostas diferentes de 0, 1 ou NA
if (!all(unlist(dados) %in% c(0, 1, NA))) {
  stop("A base deve conter somente respostas 0, 1 ou NA.")
}

# Verificar respostas ausentes
cat(
  "Total de respostas ausentes:",
  sum(is.na(dados)),
  "\n"
)

# Verificar a distribuição de respostas por item
distribuicao_itens <- lapply(
  dados,
  table,
  useNA = "ifany"
)

print(distribuicao_itens)

# Verificar se todos os itens apresentam variação nas respostas
itens_sem_variacao <- names(dados)[
  sapply(dados, function(x) {
    length(unique(na.omit(x))) < 2
  })
]

if (length(itens_sem_variacao) > 0) {
  stop(
    paste(
      "Os seguintes itens não apresentam variação:",
      paste(itens_sem_variacao, collapse = ", ")
    )
  )
}


# ============================================================
# 3. ANÁLISE DESCRITIVA DOS ITENS
# ============================================================

# Antes de ajustar o modelo TRI, é interessante conhecer
# o comportamento inicial dos itens.
# Proporção de acertos
proporcao_acertos <- colMeans(
  dados,
  na.rm = TRUE
)

# Proporção de erros
proporcao_erros <- 1 - proporcao_acertos

# Quantidade de respostas válidas por item
quantidade_validas <- colSums(
  !is.na(dados)
)

# Criar tabela descritiva
analise_descritiva <- data.frame(
  Item = colnames(dados),
  Quantidade_Respostas = quantidade_validas,
  Proporcao_Acertos = as.numeric(proporcao_acertos),
  Proporcao_Erros = as.numeric(proporcao_erros)
)

print(analise_descritiva)

# Gráfico de proporção de acertos
barplot(
  analise_descritiva$Proporcao_Acertos,
  names.arg = analise_descritiva$Item,
  main = "Proporção de acertos por item",
  xlab = "Itens",
  ylab = "Proporção de acertos",
  ylim = c(0, 1),
  col = "lightblue"
)


# ============================================================
# 4. ESCORE BRUTO DOS ESTUDANTES
# ============================================================

# Calcular o escore total de cada estudante.
#
# O escore bruto será utilizado posteriormente para comparar
# o desempenho pela TCT com a proficiência estimada pela TRI.
escore_bruto <- rowSums(
  dados,
  na.rm = FALSE
)

resultado_escore <- data.frame(
  Estudante = seq_len(nrow(dados)),
  Escore_Bruto = escore_bruto
)

# Estatísticas descritivas
estatisticas_escore <- data.frame(
  Media = mean(escore_bruto, na.rm = TRUE),
  Mediana = median(escore_bruto, na.rm = TRUE),
  Desvio_Padrao = sd(escore_bruto, na.rm = TRUE),
  Minimo = min(escore_bruto, na.rm = TRUE),
  Maximo = max(escore_bruto, na.rm = TRUE)
)

print(estatisticas_escore)

# Histograma dos escores
hist(
  escore_bruto,
  main = "Distribuição dos escores brutos",
  xlab = "Escore total",
  ylab = "Frequência",
  col = "lightblue",
  border = "white"
)


# ============================================================
# 5. AJUSTE DO MODELO LOGÍSTICO DE TRÊS PARÂMETROS (3PL)
# ============================================================

# O modelo 3PL considera três parâmetros:
#
# a = discriminação do item
# b = dificuldade do item
# c = probabilidade de acerto casual
#
# A função de probabilidade de acerto é:
#
# P(Xij = 1 | theta_j) =
#
# c_i + (1 - c_i) /
# [1 + exp(-a_i * (theta_j - b_i))]
#
# O parâmetro c representa a assíntota inferior da curva
# característica do item.
#
# O modelo será estimado por Máxima Verossimilhança Marginal
# utilizando o algoritmo EM.
mod_3PL <- mirt(
  data = dados,
  model = 1,
  itemtype = "3PL",
  method = "EM",
  technical = list(
    NCYCLES = 1000
  )
)

# Visualizar resumo do modelo
summary(mod_3PL)

# Verificar informações do ajuste
print(mod_3PL)


# ============================================================
# 6. ESTIMAÇÃO DOS PARÂMETROS DOS ITENS
# ============================================================

# Extrair os parâmetros na parametrização tradicional da TRI.
parametros_TRI <- coef(
  mod_3PL,
  IRTpars = TRUE,
  simplify = TRUE
)

# Extrair os parâmetros dos itens
itens_TRI <- as.data.frame(
  parametros_TRI$items
)

# Visualizar os parâmetros estimados
print(itens_TRI)

# Criar tabela organizada com os parâmetros
analise_parametros <- data.frame(
  Item = rownames(itens_TRI),
  a = itens_TRI$a,
  b = itens_TRI$b,
  c = itens_TRI$g
)

print(analise_parametros)


# ============================================================
# 7. INTERPRETAÇÃO DOS PARÂMETROS DOS ITENS
# ============================================================

# PARÂMETRO a - DISCRIMINAÇÃO
#
# Indica a capacidade do item de diferenciar estudantes
# com diferentes níveis de proficiência.
#
# Valores maiores indicam curvas mais inclinadas na região
# de dificuldade do item.
#
# PARÂMETRO b - DIFICULDADE
#
# Indica a posição do item na escala de proficiência.
#
# Valores maiores indicam itens mais difíceis.
#
# PARÂMETRO c - ACERTO CASUAL
#
# Representa a probabilidade de acerto quando a proficiência
# tende a valores muito baixos.
#
# Em itens de múltipla escolha, esse parâmetro está relacionado
# à possibilidade de acerto por tentativa ou conhecimento
# insuficiente.
#
# IMPORTANTE:
# O parâmetro c não deve ser interpretado automaticamente
# como o inverso do número de alternativas.
#
# Por exemplo, em uma questão com cinco alternativas,
# 0,20 seria uma referência teórica simples para um chute
# completamente aleatório, mas o parâmetro estimado pode
# assumir outro valor.


# ============================================================
# 8. CLASSIFICAÇÃO DESCRITIVA DOS PARÂMETROS
# ============================================================

# A classificação abaixo é apenas uma referência didática.
# Os limites não são universais e devem ser contextualizados.
analise_parametros$Classificacao_a <- cut(
  analise_parametros$a,
  breaks = c(-Inf, 0.65, 1.35, Inf),
  labels = c(
    "Baixa discriminação",
    "Discriminação moderada",
    "Alta discriminação"
  )
)

analise_parametros$Classificacao_b <- cut(
  analise_parametros$b,
  breaks = c(-Inf, -1, 1, Inf),
  labels = c(
    "Baixa dificuldade",
    "Dificuldade intermediária",
    "Alta dificuldade"
  )
)

print(analise_parametros)


# ============================================================
# 9. GRÁFICOS DOS PARÂMETROS DOS ITENS
# ============================================================

# Gráfico do parâmetro de discriminação
barplot(
  analise_parametros$a,
  names.arg = analise_parametros$Item,
  main = "Discriminação dos itens - Parâmetro a",
  xlab = "Itens",
  ylab = "Discriminação",
  col = "lightgreen"
)

# Gráfico do parâmetro de dificuldade
barplot(
  analise_parametros$b,
  names.arg = analise_parametros$Item,
  main = "Dificuldade dos itens - Parâmetro b",
  xlab = "Itens",
  ylab = "Dificuldade",
  col = "lightblue"
)

# Gráfico do parâmetro de acerto casual
barplot(
  analise_parametros$c,
  names.arg = analise_parametros$Item,
  main = "Acerto casual dos itens - Parâmetro c",
  xlab = "Itens",
  ylab = "Acerto casual",
  ylim = c(0, 1),
  col = "lightyellow"
)


# ============================================================
# 10. CURVAS CARACTERÍSTICAS DOS ITENS (CCI)
# ============================================================

# A Curva Característica do Item representa a probabilidade
# de acerto em função da proficiência.
#
# Eixo X: proficiência (theta)
# Eixo Y: probabilidade de acerto
#
# No modelo 3PL, a curva apresenta uma assíntota inferior
# determinada pelo parâmetro c.
plot(
  mod_3PL,
  type = "trace",
  facet_items = TRUE
)

# Interpretação:
#
# - O posicionamento horizontal da curva está relacionado
#   à dificuldade (b).
#
# - A inclinação da curva está relacionada à discriminação (a).
#
# - A assíntota inferior está relacionada ao acerto casual (c).


# ============================================================
# 11. CURVAS DE INFORMAÇÃO DOS ITENS
# ============================================================

# A informação do item representa a quantidade de informação
# que determinado item fornece sobre a proficiência.
#
# Quanto maior a informação, maior tende a ser a precisão
# da medida naquela região da escala.
plot(
  mod_3PL,
  type = "infotrace"
)

# Cada curva representa a informação fornecida por um item
# ao longo dos diferentes níveis de proficiência.


# ============================================================
# 12. CURVA DE INFORMAÇÃO DO TESTE
# ============================================================

# A informação total do teste corresponde à soma das
# informações fornecidas pelos itens, sob a hipótese
# de independência local.
plot(
  mod_3PL,
  type = "info"
)

# Interpretação:
#
# A curva permite identificar em quais regiões da escala
# de proficiência o teste apresenta maior precisão.
#
# Um teste pode apresentar maior informação para estudantes
# com proficiência intermediária e menor informação
# nas extremidades da escala.


# ============================================================
# 13. ERRO-PADRÃO CONDICIONAL DA MEDIDA
# ============================================================

# O erro-padrão da proficiência varia ao longo da escala.
#
# Em condições usuais, o erro-padrão condicional pode ser
# obtido pelo inverso da raiz quadrada da informação do teste.
#
# EP(theta) = 1 / sqrt(Informação(theta))
# Criar uma grade de proficiências
grade_theta <- seq(
  from = -4,
  to = 4,
  length.out = 161
)

theta_matriz <- matrix(
  grade_theta,
  ncol = 1
)

# Calcular informação do teste
informacao_teste <- testinfo(
  mod_3PL,
  Theta = theta_matriz
)

# Calcular erro-padrão condicional
erro_padrao_condicional <- 1 / sqrt(
  informacao_teste
)

# Criar tabela
analise_informacao <- data.frame(
  Proficiência = grade_theta,
  Informacao = as.numeric(informacao_teste),
  Erro_Padrao = as.numeric(erro_padrao_condicional)
)

# Visualizar tabela
print(head(analise_informacao))

# Gráfico de informação do teste
plot(
  analise_informacao$Proficiência,
  analise_informacao$Informacao,
  type = "l",
  lwd = 2,
  main = "Informação do teste ao longo da escala",
  xlab = "Proficiência",
  ylab = "Informação"
)

# Gráfico do erro-padrão condicional
plot(
  analise_informacao$Proficiência,
  analise_informacao$Erro_Padrao,
  type = "l",
  lwd = 2,
  main = "Erro-padrão condicional da medida",
  xlab = "Proficiência",
  ylab = "Erro-padrão"
)


# ============================================================
# 14. AJUSTE DOS ITENS AO MODELO 3PL
# ============================================================

# Avaliar o ajuste dos itens ao modelo.
ajuste_itens <- tryCatch(
  itemfit(mod_3PL),
  error = function(e) {
    message("Não foi possível calcular itemfit: ", e$message)
    NULL
  }
)

print(ajuste_itens)

# A análise permite identificar itens cujo comportamento
# observado apresenta diferenças em relação ao comportamento
# esperado pelo modelo.
#
# Valores-p baixos podem indicar desajuste, mas devem ser
# interpretados considerando tamanho amostral e multiplicidade
# de testes.


# ============================================================
# 15. AJUSTE GLOBAL DO MODELO
# ============================================================

# Estatística M2 para avaliar o ajuste global.
ajuste_global <- tryCatch(
  M2(mod_3PL),
  error = function(e) {
    message("Não foi possível calcular M2: ", e$message)
    NULL
  }
)

print(ajuste_global)

# A estatística M2 permite avaliar o ajuste global do modelo,
# quando suas condições de aplicação são atendidas.


# ============================================================
# 16. DEPENDÊNCIA LOCAL ENTRE OS ITENS
# ============================================================

# A independência local pressupõe que, condicionada à
# proficiência, a resposta a um item não depende da resposta
# dada a outro item.
# Utilizar o Q3 de Yen para investigar dependência local.
residuos_Q3 <- residuals(
  mod_3PL,
  type = "Q3"
)

print(residuos_Q3)

# Visualizar matriz de correlações residuais
heatmap(
  residuos_Q3,
  main = "Dependência local entre os itens - Q3",
  scale = "none"
)

# Valores residuais elevados podem indicar dependência local,
# por exemplo, quando dois itens compartilham o mesmo texto-base,
# estímulo ou contexto.


# ============================================================
# 17. ESTIMAÇÃO DAS PROFICIÊNCIAS DOS ESTUDANTES
# ============================================================

# Estimar as proficiências pelo método EAP
# (Expected A Posteriori).
#
# O EAP utiliza a distribuição a priori da proficiência
# e a informação das respostas para obter a estimativa.
prof_estudantes <- fscores(
  mod_3PL,
  method = "EAP",
  full.scores.SE = TRUE
)

# Transformar em data frame
prof_estudantes <- as.data.frame(
  prof_estudantes
)

# Identificar as colunas de proficiência e erro-padrão
coluna_theta <- grep(
  "^F1$",
  names(prof_estudantes),
  value = TRUE
)

coluna_se <- grep(
  "^SE_F1$",
  names(prof_estudantes),
  value = TRUE
)

if (length(coluna_theta) != 1 || length(coluna_se) != 1) {
  stop(
    "Verifique os nomes das colunas retornadas por fscores()."
  )
}

# Criar tabela final
resultado_prof <- data.frame(
  Estudante = seq_len(nrow(dados)),
  Proficiência = prof_estudantes[[coluna_theta]],
  Erro_Padrao = prof_estudantes[[coluna_se]]
)

print(head(resultado_prof))


# ============================================================
# 18. ESTATÍSTICAS DESCRITIVAS DAS PROFICIÊNCIAS
# ============================================================

estatisticas_prof <- data.frame(
  Media = mean(
    resultado_prof$Proficiência,
    na.rm = TRUE
  ),
  Mediana = median(
    resultado_prof$Proficiência,
    na.rm = TRUE
  ),
  Desvio_Padrao = sd(
    resultado_prof$Proficiência,
    na.rm = TRUE
  ),
  Minimo = min(
    resultado_prof$Proficiência,
    na.rm = TRUE
  ),
  Maximo = max(
    resultado_prof$Proficiência,
    na.rm = TRUE
  )
)

print(estatisticas_prof)

# Histograma das proficiências
hist(
  resultado_prof$Proficiência,
  main = "Distribuição das proficiências - TRI 3PL",
  xlab = "Proficiência (theta)",
  ylab = "Frequência",
  col = "lightgreen",
  border = "white"
)

# Histograma dos erros-padrão das proficiências
hist(
  resultado_prof$Erro_Padrao,
  main = "Distribuição dos erros-padrão das proficiências",
  xlab = "Erro-padrão",
  ylab = "Frequência",
  col = "lightblue",
  border = "white"
)


# ============================================================
# 19. INTERVALOS DE CONFIANÇA DAS PROFICIÊNCIAS
# ============================================================

# Construir intervalos aproximados de 95% para as estimativas.
#
# A aproximação considera a proficiência estimada e seu
# erro-padrão individual.
resultado_prof$Limite_Inferior_95 <- (
  resultado_prof$Proficiência -
    1.96 * resultado_prof$Erro_Padrao
)

resultado_prof$Limite_Superior_95 <- (
  resultado_prof$Proficiência +
    1.96 * resultado_prof$Erro_Padrao
)

print(head(resultado_prof))

# IMPORTANTE:
# Esses intervalos são aproximações baseadas no erro-padrão.
# Sua interpretação depende das propriedades da estimativa
# e do modelo ajustado.


# ============================================================
# 20. COMPARAÇÃO ENTRE ESCORE BRUTO E PROFICIÊNCIA TRI
# ============================================================

# Comparar o número de acertos com a proficiência estimada.
comparacao_escore <- data.frame(
  Estudante = seq_len(nrow(dados)),
  Escore_Bruto = escore_bruto,
  Proficiência = resultado_prof$Proficiência
)

# Correlação de Pearson
correlacao_escore <- cor(
  comparacao_escore$Escore_Bruto,
  comparacao_escore$Proficiência,
  use = "complete.obs",
  method = "pearson"
)

cat(
  "Correlação entre escore bruto e proficiência:",
  correlacao_escore,
  "\n"
)

# Gráfico de dispersão
plot(
  comparacao_escore$Escore_Bruto,
  comparacao_escore$Proficiência,
  main = "Escore bruto x Proficiência TRI",
  xlab = "Escore bruto",
  ylab = "Proficiência",
  pch = 19
)

abline(
  lm(
    Proficiência ~ Escore_Bruto,
    data = comparacao_escore
  ),
  lwd = 2
)

# A comparação permite verificar a relação entre o número
# de acertos e a proficiência estimada pelo modelo.
#
# Estudantes com o mesmo escore bruto podem apresentar
# proficiências diferentes, pois a TRI considera os parâmetros
# dos itens respondidos.


# ============================================================
# 21. ANÁLISE DO ERRO-PADRÃO POR NÍVEL DE PROFICIÊNCIA
# ============================================================

# Agrupar os estudantes em faixas de proficiência.
#
# O objetivo é verificar se a precisão da medida varia
# conforme o nível de desempenho.
resultado_prof$Faixa_Prof <- cut(
  resultado_prof$Proficiência,
  breaks = c(-Inf, -2, -1, 0, 1, 2, Inf),
  labels = c(
    "Muito baixa",
    "Baixa",
    "Média baixa",
    "Média alta",
    "Alta",
    "Muito alta"
  )
)

# Calcular o erro-padrão médio por faixa
analise_ep_faixa <- aggregate(
  Erro_Padrao ~ Faixa_Prof,
  data = resultado_prof,
  FUN = mean,
  na.rm = TRUE
)

print(analise_ep_faixa)

# Calcular a quantidade de estudantes por faixa
quantidade_faixa <- as.data.frame(
  table(resultado_prof$Faixa_Prof)
)

names(quantidade_faixa) <- c(
  "Faixa_Prof",
  "Quantidade"
)

print(quantidade_faixa)


# ============================================================
# 22. ANÁLISE DE ITENS QUE MERECEM REVISÃO
# ============================================================

# Identificar itens com características que merecem
# investigação pedagógica e psicométrica.
#
# Os limites são referências iniciais, não critérios
# automáticos para exclusão de itens.
itens_revisao <- analise_parametros

itens_revisao$Revisar <- with(
  itens_revisao,
  a < 0.65 | b < -3 | b > 3 | c > 0.35
)

print(
  itens_revisao[
    itens_revisao$Revisar,
  ]
)

# IMPORTANTE:
# Um item não deve ser excluído automaticamente por apresentar
# determinado parâmetro.
#
# É necessário investigar:
# - conteúdo pedagógico;
# - clareza do enunciado;
# - qualidade dos distratores;
# - alinhamento ao descritor ou habilidade;
# - funcionamento diferencial;
# - ajuste ao modelo;
# - quantidade de respostas válidas.


# ============================================================
# 23. EXPORTAÇÃO DOS RESULTADOS PARA EXCEL
# ============================================================

# Organizar as análises em diferentes planilhas.
resultados_exportacao <- list(
  "Descritiva_Itens" = analise_descritiva,
  "Escores_Brutos" = resultado_escore,
  "Estatisticas_Escore" = estatisticas_escore,
  "Parametros_3PL" = analise_parametros,
  "Informacao_Teste" = analise_informacao,
  "Proficiências" = resultado_prof,
  "Estatisticas_Prof" = estatisticas_prof,
  "Comparacao_Escore_TRI" = comparacao_escore,
  "Erro_Padrao_Faixa" = analise_ep_faixa,
  "Quantidade_Faixa" = quantidade_faixa,
  "Itens_Revisao" = itens_revisao
)

# Acrescentar resultados de ajuste quando disponíveis
if (!is.null(ajuste_itens)) {
  resultados_exportacao[["Ajuste_Itens"]] <-
    as.data.frame(ajuste_itens)
}

if (!is.null(ajuste_global)) {
  resultados_exportacao[["Ajuste_Global"]] <-
    as.data.frame(ajuste_global)
}

# Exportar arquivo Excel
write.xlsx(
  resultados_exportacao,
  file = "Resultados_TRI_3PL.xlsx",
  overwrite = TRUE
)

cat(
  "Análise TRI 3PL concluída!\n",
  "Arquivo Resultados_TRI_3PL.xlsx exportado com sucesso.\n"
)


# ============================================================
# FIM DO SCRIPT
# ============================================================
