% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/trt_binary.R
\name{trt_binary}
\alias{trt_binary}
\title{Unidimensional Binary (Dichotomous) Testlet Response Theory Estimation}
\usage{
trt_binary(
  data,
  group,
  model = c("RaschT", "2PLT", "3PLT", "BiFT"),
  method = c("EM", "MLE"),
  control = list()
)
}
\arguments{
\item{data}{A data.frame of binary responses (0/1). Rows=persons, Cols=items in testlets.}

\item{group}{A list defining testlet structures. Example: \code{list(c(1,2,3), c(4,5,6))}.}

\item{model}{Character. One of "RaschT" (Rasch Testlet), "2PLT" (2-Parameter Logistic Testlet), "3PLT" (3-Parameter Logistic Testlet), "BiFT" (Bifactor).}

\item{method}{Character. "EM" (Marginal Maximum Likelihood via Expectation-Maximization) or "MLE" (Joint Maximum Likelihood).}

\item{control}{A \code{list} of control parameters for the estimation algorithm:
\itemize{
\item \code{max_iter}: Maximum number of EM iterations (default = 100).
\item \code{converge_tol}: Convergence criterion for parameter change (default = 1e-4).
\item \code{theta_range}: Numeric vector of length 2 specifying the integration
grid bounds (default = c(-4, 4)).
\item \code{quad_points}: Number of quadrature points (default = 21).
\item \code{verbose}: Logical; if \code{TRUE}, prints progress to console.
}}
}
\value{
A list containing:
\itemize{
\item \code{item_params}: Estimated item parameters.
\item \code{person_params}: Estimated person abilities and testlet effects.
\item \code{model_fit}: A data frame containing iterations and fit statistics such as Akaike’s Information Criterion (AIC), the Bayesian Information Criterion (BIC), and Log-Likelihood.
}
}
\description{
Estimates item and person parameters for Unidimensional Binary (Dichotomous) Testlet response models
using Penalized Expectation-Maximization or
Joint Maximum Likelihood Estimation with stabilization.
}
\examples{
  # --- Quick Example (small data) ---
  set.seed(1)
  n <- 50
  J <- 4
  theta <- rnorm(n)
  gamma <- rnorm(n, 0, 0.5)
  resp <- matrix(NA, n, J)
  colnames(resp) <- paste0("Item_", 1:J)
  b <- c(-0.5, 0, 0.5, 1)
  for(j in 1:J) {
    p <- 1 / (1 + exp(-(theta + gamma - b[j])))
    resp[, j] <- rbinom(n, 1, p)
  }
  res <- trt_binary(
    data = as.data.frame(resp),
    group = list(1:2, 3:4),
    model = "2PLT",
    method = "EM",
    control = list(max_iter = 5, verbose = FALSE)
  )
  head(res$item_params)

 \donttest{
  # --- Full Example: Simulation (2PLT) ---
  set.seed(2025)
  n_persons <- 500
  n_testlets <- 3
  items_per_testlet <- 3
  n_items <- n_testlets * items_per_testlet

  # 1. Generate Parameters
  # Discrimination (a): Varying -> 2PLT
  a_true <- runif(n_items, 0.8, 1.5)
  # Difficulty (b)
  b_true <- seq(-1, 1, length.out = n_items)
  # Testlet Variances (Sigma)
  sigma_true <- c(1.0, 1.5, 2.0)

  # 2. Generate Person Params
  theta_true <- rnorm(n_persons, 0, 1)
  gamma_matrix <- matrix(0, nrow = n_persons, ncol = n_testlets)
  for(d in 1:n_testlets) {
    gamma_matrix[, d] <- rnorm(n_persons, 0, sigma_true[d])
  }

  # 3. Generate Responses
  resp_matrix <- matrix(0, nrow = n_persons, ncol = n_items)
  colnames(resp_matrix) <- paste0("Item_", 1:n_items)
  group_list <- list()

  idx_counter <- 1
  for(d in 1:n_testlets) {
    indices <- idx_counter:(idx_counter + items_per_testlet - 1)
    group_list[[d]] <- indices

    for(i in indices) {
      # 2PLT Model: a * (theta + gamma - b)
      lin <- a_true[i] * (theta_true + gamma_matrix[, d] - b_true[i])
      prob <- 1 / (1 + exp(-lin))
      resp_matrix[, i] <- rbinom(n_persons, 1, prob)
    }
    idx_counter <- idx_counter + items_per_testlet
  }
  df_sim <- as.data.frame(resp_matrix)

  # 4. Run Estimation
  # We use "2PLT" because data was generated with varying 'a'
  res <- trt_binary(
    data = df_sim,
    group = group_list,
    model = "2PLT",
    method = "EM",
    control = list(max_iter = 20, verbose = FALSE)
  )

  head(res$item_params)
  head(res$person_params)
  }
}
