longitudinal_grmfit: Internal Function: Fit Constrained Longitudinal Graded...

In grmtree: Recursive Partitioning for Graded Response Models

Internal Function: Fit Constrained Longitudinal Graded Response Model

Description

Fits a constrained two-factor longitudinal graded response model (GRM) to wide-format item response data from two time points. This is an internal function called by longitudinal_grmtree during model-based recursive partitioning and is not intended to be used directly.

Usage

longitudinal_grmfit(
  y,
  x = NULL,
  start = NULL,
  weights = NULL,
  offset = NULL,
  ...,
  estfun = FALSE,
  object = FALSE
)

Arguments

y	A numeric matrix of item responses in wide format. The first n_items columns contain responses at Time 1 (T1) and the next n_items columns contain responses at Time 2 (T2), for a total of 2 * n_items columns. Each row represents one individual. The number of columns must be even and at least 4.
x	Optional predictor matrix. Handled internally by the MOB framework and not used directly in model fitting.
start	Optional starting values for model parameters. Passed to mirt.
weights	Optional case weights. Not currently used.
offset	Optional offset. Not currently used.
...	Additional arguments passed to mirt.
estfun	Logical indicating whether to compute empirical estimating (score) functions for the MOB parameter instability tests. When TRUE, standard errors are computed during model fitting (SE = TRUE) and estfun.AllModelClass is called to extract the score contributions for each individual. Default is FALSE.
object	Logical indicating whether to return the full mirt model object. Default is FALSE. Set to TRUE when the fitted model is needed for post-hoc analyses (e.g., in rs_characterize).

Details

This production version builds the equality constraints directly from the known parameter structure rather than fitting an unconstrained model first to discover that structure. Because the function is called hundreds of times during tree construction, avoiding the extra (unconstrained) model fit at every node yields a substantial speed-up with no change in results.

Constrained Two-Factor Longitudinal GRM

The function specifies a two-factor GRM where the latent factors \theta_{T1} and \theta_{T2} represent the construct at Time 1 and Time 2, respectively. The model structure is:

\theta_{T1} \sim N(0, 1)

\theta_{T2} \sim N(\mu_{T2}, \sigma^2_{T2})

Cov(\theta_{T1}, \theta_{T2}) = \sigma_{12}

Items 1 through M load on \theta_{T1} and items M+1 through 2M load on \theta_{T2}, where M is the number of items per time point.

Under the null hypothesis of no response shift, item parameters are constrained equal across time points. For each item m:

• Discrimination: a_{1,m} = a_{2,m+M} (the T1 item's loading on \theta_{T1} equals the T2 item's loading on \theta_{T2})

• Thresholds: b_{k,m} = b_{k,m+M} for all category thresholds k = 1, \ldots, K_m

The number of threshold constraints per item pair is determined by the minimum number of observed response categories across T1 and T2 for that item (minus 1). This handles cases where sparse response categories at one time point produce fewer estimated thresholds (e.g., category 5 may be empty at T1 but observed at T2).

Constraint Syntax

Constraints are specified using mirt's CONSTRAIN syntax:

• Discrimination: (i, a1, j, a2) constrains item i's a1 parameter to equal item j's a2 parameter

• Thresholds: (i, j, dk) constrains the dk threshold to be equal between items i and j

where i is the T1 item index and j = i + n_items is the corresponding T2 item index. The baseline factor is fixed at N(0,1) as the reference while the follow-up mean and variance are freely estimated (identified by the cross-time item-equality constraints).

Technical Details

The EM algorithm is run with a maximum of 1000 cycles (technical = list(NCYCLES = 1000)) to accommodate the complexity of the constrained two-factor model. Verbose output from mirt is suppressed. If the model fails to converge or encounters an error, the function stops with an informative error message.

Value

A list containing:

coefficients	Item parameter estimates from mirt::coef(fit, IRTpars = TRUE, simplify = TRUE), including discrimination (a1, a2) and threshold (b1, ..., bK) parameters for all 2 * n_items items, plus latent trait means and covariance matrix.
objfun	Negative log-likelihood of the fitted model. Used by MOB to evaluate splits via partitioned log-likelihood maximization.
estfun	Empirical estimating (score) functions if estfun = TRUE; NULL otherwise. An N x p matrix where N is the number of individuals and p is the number of model parameters. Used by MOB for score-based structural change tests.
object	The full SingleGroupClass model object if object = TRUE; NULL otherwise.

See Also

grmtree fits a Graded Response Model Tree, longitudinal_grmtree for the main tree-fitting function that calls this internally, mirt for the underlying IRT estimation engine, rs_characterize for post-hoc response shift testing within terminal nodes

grmtree documentation built on Sept. 2, 2026, 1:07 a.m.