% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-advanced.R
\name{compute_information}
\alias{compute_information}
\title{Compute design-weighted precision curves for ordered many-facet fits}
\usage{
compute_information(fit, theta_range = c(-6, 6), theta_points = 201L)
}
\arguments{
\item{fit}{Output from \code{\link[=fit_mfrm]{fit_mfrm()}}.}

\item{theta_range}{Numeric vector of length 2 giving the range of theta
values. Default \code{c(-6, 6)}.}

\item{theta_points}{Integer number of points at which to evaluate
information. Default \code{201}.}
}
\value{
An object of class \code{mfrm_information} (named list) with:
\itemize{
\item \code{tif}: tibble with columns \code{Theta}, \code{Information}, \code{SE}. The
\code{Information} column stores the design-weighted precision value.
\item \code{iif}: tibble with columns \code{Theta}, \code{Facet}, \code{Level}, \code{Information},
and \code{Exposure}. Here too, \code{Information} stores a design-weighted
contribution value retained under that column name for compatibility.
\item \code{theta_range}: the evaluated theta range.
}
}
\description{
Calculates design-weighted score-variance curves across the latent
trait (theta) for a fitted ordered-category \code{RSM}, \code{PCM}, or bounded
\code{GPCM} model. Returns both an overall precision curve (\verb{$tif}) and
per-facet-level contribution curves (\verb{$iif}) based on the realized
observation pattern.
}
\details{
For \code{RSM} / \code{PCM}, the score variance at theta for one observed design cell
is:
\deqn{I(\theta) = \sum_{k=0}^{K} P_k(\theta) \left(k - E(\theta)\right)^2}
where \eqn{P_k} is the category probability and \eqn{E(\theta)} is the
expected score at theta. In \code{mfrmr}, these cell-level variances are then
aggregated with weights taken from the realized observation counts in
\code{fit$prep$data}.

The resulting total curve is therefore a design-weighted precision screen
rather than a pure textbook test-information function for an abstract fixed
item set. The associated standard error summary is still
\eqn{SE(\theta) = 1 / \sqrt{I(\theta)}} for positive information values.

In an ordered Rasch-family model, category discrimination is fixed at 1, so
this score-variance representation is the natural conditional information
identity rather than a separate approximation. For binary data it reduces to
the familiar \eqn{p(\theta)\{1 - p(\theta)\}} form. For \code{PCM}, the package
evaluates each observed design cell using the threshold vector associated
with that cell's realized \code{step_facet} level. For bounded \code{GPCM}, the
same design-weighted score variance is scaled by the squared discrimination
attached to the realized \code{slope_facet} level, which is the
\eqn{a_j^2 \cdot \mathrm{Var}(T \mid \theta)} item-information identity that
Muraki (1993, Equation 10) derives by applying Samejima's (1974)
polytomous information formula to the GPCM kernel of Muraki (1992).
}
\section{What \code{tif} and \code{iif} mean here}{

In \code{mfrmr}, this helper supports ordered-category \code{RSM}, \code{PCM}, and the
current bounded \code{GPCM} fit. The total curve (\verb{$tif}) is the sum of
design-weighted cell contributions across all non-person facet levels in the
fitted model. The facet-level contribution curves (\verb{$iif}) keep those
weighted contributions separated, so you can see which observed rater
levels, criteria, or other facet levels are driving precision at different
parts of the scale. For \code{PCM}, step-facet-specific thresholds are respected
when each observed design cell is evaluated. For bounded \code{GPCM}, those
same cell-level variances are additionally scaled by the squared
discrimination associated with the realized \code{slope_facet} level.
}

\section{What this quantity does not justify}{

\itemize{
\item It is not a textbook many-facet test-information function for an abstract
fixed item set.
\item It should not be used as if it were design-free evidence about a form's
precision independent of the realized observation pattern.
\item It does not currently extend beyond the ordered-category \code{RSM} / \code{PCM} /
bounded \code{GPCM} family implemented by \code{\link[=fit_mfrm]{fit_mfrm()}}.
}
}

\section{When to use this}{

Use \code{compute_information()} when you want a design-weighted precision screen
for an \code{RSM}, \code{PCM}, or bounded \code{GPCM} fit along the latent
continuum. In practice:
\itemize{
\item start with the total precision curve for overall targeting across the
realized observation pattern
\item inspect facet-level contribution curves when you want to see which raters,
criteria, or other facet levels account for more of that design-weighted
precision
\item widen \code{theta_range} if you expect extreme measures and want to inspect the
tails explicitly
}
}

\section{Choosing the theta grid}{

The defaults (\code{theta_range = c(-6, 6)}, \code{theta_points = 201}) work well for
routine inspection. Expand the range if person or facet measures extend into
the tails, and increase \code{theta_points} only when you need a smoother grid
for reporting or custom graphics.
}

\section{References}{

The ordered-category probability structures come from Andrich's \code{RSM}
formulation and Masters' \code{PCM}. The bounded \code{GPCM} information identity
\eqn{a_j^2 \cdot \mathrm{Var}(T \mid \theta)} is derived in Muraki
(1993, Equation 10) by applying Samejima's (1974) general polytomous
information formula \eqn{I_j(\theta) = \sum_k P_{jk}(\theta)
[-\partial^2 \ln P_{jk} / \partial \theta^2]} to the GPCM probability
kernel of Muraki (1992). For the integer scoring function
\eqn{T_k = k} used by \code{mfrmr}, this reduces to
\eqn{a_j^2 \cdot \mathrm{Var}(K \mid \theta)}. In \code{mfrmr}, those formulas
are applied to the realized many-facet observation design, so the output
should be read as a design-weighted precision summary rather than as a
design-free abstract test function.
\itemize{
\item Andrich, D. (1978). \emph{A rating formulation for ordered response
categories}. Psychometrika, 43(4), 561-573.
\item Masters, G. N. (1982). \emph{A Rasch model for partial credit scoring}.
Psychometrika, 47(2), 149-174.
\item Muraki, E. (1992). \emph{A generalized partial credit model: Application
of an EM algorithm}. Applied Psychological Measurement, 16(2),
159-176. \doi{10.1177/014662169201600206} (See Equations 6, 10, and
13 for the probability kernel and the
\eqn{\partial P_k / \partial \theta = a_j P_k (k - E[K])}
derivative used by all GPCM helpers in \code{mfrmr}.)
\item Muraki, E. (1993). \emph{Information functions of the generalized
partial credit model}. Applied Psychological Measurement, 17(4),
351-363. \doi{10.1177/014662169301700403} (Equation 10 derives the
item information function for the GPCM,
\eqn{I_j(\theta) = D^2 a_j^2 \mathrm{Var}(T \mid \theta)}, by
applying Samejima's (1974) polytomous information formula to the
GPCM kernel; this is the canonical reference for \code{compute_information()}
under bounded \code{GPCM}.)
\item Samejima, F. (1974). \emph{Normal ogive model on the continuous
response level in the multidimensional latent space}.
Psychometrika, 39, 111-121. (Source for the general polytomous
information formula that Muraki 1993 specializes to the GPCM.)
}
}

\section{Interpreting output}{

\itemize{
\item \verb{$tif}: design-weighted precision curve data with theta, Information, and SE.
\item \verb{$iif}: design-weighted facet-level contribution curves for the fitted
non-person facets.
\item Higher information implies more precise measurement at that theta.
\item SE is inversely related to information.
\item Peaks in the total curve show the trait region where the realized
calibration is most informative.
\item Facet-level curves help explain \emph{which observed facet levels} contribute
to those peaks; they are not standalone item-information curves and should
be read as design contributions.
}
}

\section{How to read the main columns}{

\itemize{
\item \code{Theta}: point on the latent continuum where the curve is evaluated.
\item \code{Information}: design-weighted precision value at that theta.
\item \code{SE}: approximate \code{1 / sqrt(Information)} summary for positive values.
\item \code{Exposure}: total realized observation weight contributing to a facet-level
curve in \verb{$iif}.
}
}

\section{Recommended next step}{

Compare the precision peak with person/facet locations from a Wright map or
related diagnostics. If you need to decide how strongly SE/CI language can
be used in reporting, follow with \code{\link[=precision_review_report]{precision_review_report()}}.
}

\section{Typical workflow}{

\enumerate{
\item Fit a model with \code{\link[=fit_mfrm]{fit_mfrm()}}.
\item Run \code{compute_information(fit)}.
\item Plot with \code{plot_information(info, type = "tif")}.
\item If needed, inspect facet contributions with
\code{plot_information(info, type = "iif", facet = "Rater")}.
}
}

\examples{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 30)
info <- compute_information(fit)
head(info$tif)
info$tif$Theta[which.max(info$tif$Information)]
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=plot_information]{plot_information()}}
}
