% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/information.R
\name{item_info}
\alias{item_info}
\title{Item Information Function}
\usage{
item_info(item_params, theta = seq(-4, 4, by = 0.1), model = NULL, D = 1)
}
\arguments{
\item{item_params}{A data frame of item parameters, typically the
\code{item_params} element returned by \code{\link{binary_irt}},
\code{\link{polytomous_irt}}, or \code{\link{mixed_irt}}. The function
auto-detects the model of each item from the available columns
(discrimination, difficulty, guessing, thresholds/steps) or from a
\code{model} column if present. All models in the package are supported:
Rasch, 2PL, 3PL, GRM, GPCM, and PCM.}

\item{theta}{A numeric vector of ability values at which to evaluate the
information (default = \code{seq(-4, 4, by = 0.1)}).}

\item{model}{Optional character string (applied to all items) or character
vector of length equal to the number of items, forcing the model family
used for each item. Advanced use only; when \code{NULL} (default) the model
is detected automatically.}

\item{D}{Scaling constant for the dichotomous logistic metric (default
\code{1}, matching the estimation functions in this package). Advanced
users who calibrated on the normal-metric scale may set \code{D = 1.702}.}
}
\value{
A numeric matrix with one row per item and one column per theta point.
Row names are the item names and column names are the theta values.
}
\description{
Computes the Fisher item information function for every item at a set of
ability (theta) points. The item information function shows how precisely an
item measures ability across the latent trait continuum: high information at
a given theta means the item discriminates well among examinees located
there. It is the building block of the test information function
(\code{\link{test_info}}) and of the conditional standard error of
measurement.
}
\details{
For dichotomous models the information is
\eqn{I(\theta) = (Da)^2 P(\theta)(1 - P(\theta))} for the Rasch and 2PL
models, and the standard Birnbaum form
\eqn{I(\theta) = (Da)^2 (1 - c)(1 - P^*)P^{*2} / P} for the 3PL model,
where \eqn{P^*} is the 2PL probability and \eqn{P} the full 3PL probability
(this reduces to the 2PL expression when the guessing parameter \eqn{c = 0}).
For polytomous models the general expected-information formula
\eqn{I(\theta) = \sum_k (\partial P_k / \partial \theta)^2 / P_k} is used,
which for the GPCM and PCM equals \eqn{(Da)^2 \mathrm{Var}(X \mid \theta)}.
}
\examples{
  # --- Example 1: dichotomous items ---
  set.seed(123)
  sim <- sim_irt(n_people = 400,
                 item_structure = list(list(model = "2PL", n_items = 6)))
  fit <- binary_irt(sim$resp, model = "2PL", method = "EM",
                    control = list(max_iter = 15, verbose = FALSE))

  # Information for each item at a grid of abilities
  info <- item_info(fit$item_params, theta = seq(-3, 3, by = 0.5))
  round(info, 3)

  \donttest{
  # --- Example 2: polytomous (GRM) items ---
  simp <- sim_irt(n_people = 400,
                  item_structure = list(list(model = "GRM", n_items = 5,
                                             categories = 4)))
  fitp <- polytomous_irt(simp$resp, model = "GRM", method = "EM",
                         control = list(max_iter = 15, verbose = FALSE))
  item_info(fitp$item_params, theta = c(-2, -1, 0, 1, 2))
  }
}
\seealso{
\code{\link{test_info}}, \code{\link{binary_irt}},
\code{\link{polytomous_irt}}
}
