Review MML sensitivity to the quadrature grid

Refit one ordered-response MML model to the same supplied response data at two or more Gauss–Hermite quadrature counts. The original fit is reused at its own quadrature count; all other fits reuse its stored model, identification, anchor, interaction, optimizer, and population settings.

Usage

mml_quadrature_sensitivity(
  fit,
  data,
  quad_points = c(31L, 41L),
  theta_range = c(-4, 4),
  theta_points = 161L,
  adaptive_quad_points = NULL
)

gpcm_mml_quadrature_sensitivity(
  fit,
  data,
  quad_points = c(31L, 41L),
  theta_range = c(-4, 4),
  theta_points = 161L,
  adaptive_quad_points = NULL
)

Arguments

fit: An RSM, PCM, or GPCM MML mfrm_fit returned by fit_mfrm(). gpcm_mml_quadrature_sensitivity() accepts only GPCM fits.
data: The original response data.frame used to create fit. Prepared response rows are compared semantically after refitting; row order may differ, but changed observations fail closed.
quad_points: At least two distinct positive integers, including the quadrature count stored on fit. The default c(31, 41) is a comparison starting point, not a claim that either grid is adequate for the data. Refits retain the source fit's fixed or adaptive integration mode.
theta_range: Two finite values defining the common ability grid used for fitted category-probability comparison.
theta_points: Number of common-grid ability points; at least 21.
adaptive_quad_points: Optional vector of at least two distinct integer orders >= 3, for example c(31, 61). Adds a per-Person quadrature_review at each fit's fixed parameters, comparing a fixed-prior grid with mode/curvature-adapted grids. This separates integration error from parameter changes during refitting. Inspect changes between adaptive orders too; neither grid is certified exact. Also available for two slope families as a numerical diagnostic; it does not add Person scoring or change the fitted integration method.

Value

An object of class mfrm_quadrature_sensitivity containing:

summary: one comparison row per quadrature grid relative to the original fit, including likelihood, measurement-coordinate, probability, EAP, and posterior-SD changes;
quadrature_review: when requested, unrounded per-Person fixed/adaptive log-marginal, EAP and posterior-SD differences, adaptive-order changes, mode/curvature and computation status. Unavailable rows retain their reason. summary() also supplies a compact quadrature_overview;
runs: likelihood, gradient, curvature, population-scale, and readiness details for each fit;
slopes: component-slope estimates, raw diagnostic SEs and freshly checked 95% model intervals. The summary reports endpoint changes among jointly eligible levels and counts changes in interval availability. One-family slopes have geometric mean one; two-family scale references differ;
intervals: for two families, saved mfrm_slope_intervals objects named by quadrature count, with their numerical checks and cautions;
conditions: warnings and messages from refitting and result extraction;
fits: the reference and refitted mfrm_fit objects;
settings and notes: the fixed comparison contract and interpretation boundary.

The object supports print(), summary(), as.data.frame(), and the existing apa_table() list route (for example apa_table(out)).

Details

This is an explicit refit diagnostic: neither summary.mfrm_fit() nor diagnose_mfrm() invokes it automatically. It reports continuous changes rather than classifying a fit as quadrature-stable or unstable. In particular, it does not select a cutoff for acceptable changes, make unavailable standard errors valid, or resolve other warnings about the fit.

The probability comparison evaluates every observed combination of non-Person facet levels on the same theta grid. It includes fitted two-way facet interactions and, for GPCM, the complete-predictor slope action. Same-Person EAP and posterior-SD changes use each fit's corresponding quadrature count. A one-point grid has no public scoring route, so those two changes are NA when it is the reference.

Explicit intercept-only and covariate population models reuse the retained person table, factor coding and formula, with design equality checked by Person. Older fits without that data cannot be replayed.

Raw slope and population-SD standard errors are computed from each local observed-information Hessian for diagnostic comparison only. The public parameter-level SEEligible state remains unchanged.

Two slope families

For a two-family GPCM, refits preserve the ordered slope owners, fixed N(0,1) population, score ladder, engine, integration method and stopping controls (em_score_tol for fixed-grid EM or reltol for adaptive direct MML). Each refit reconstructs the source initialization policy from the observed data. Fixed-grid EM uses the neutral vector; adaptive fits retain either neutral-only or neutral-plus-EM initialization. Older adaptive fits without this setting retain the earlier neutral-only procedure. The reference estimate is not used as a new starting vector. Component slopes retain SlopeOwner and ScaleReference: the first family has geometric mean one; the second is free on the fixed ability scale. Category-probability comparisons use the product of both slopes.

For both two-family engines, intervals contains the separately checked experimental confint() result for each grid, including failed checks, cautions and missing bounds. For example, after comparing quad_points = c(31, 61), use plot(out$intervals$q61) and apa_table(out$intervals$q61, which = "numerical_checks"). These checks also evaluate q versus 2q-1 at that fit's saved parameters without another refit. Passing these checks does not establish sampling coverage or resolve other warnings about the fitted model. Adaptive fits use their moving-node objective for both the information and the higher-order comparison. Person-score comparisons in summary remain unavailable for two families: EAP and posterior-SD changes there are NA, not zero. With adaptive_quad_points, the separate quadrature_review table evaluates posterior moments and log marginal likelihoods at each unchanged calibration. These diagnostic integrals do not enable predict_mfrm_units() or supply Person intervals. The effective slope is the product of both facet slopes; moving the integration grid retains the original N(0,1) density and its Jacobian. This does not provide adaptive EM, update estimates or repair their intervals.

More quadrature points improve the numerical approximation, not the amount of observed information. In a sparse design, a small group of candidates rated many times may need a finer grid than candidates with few ratings. Inspect interval availability and measured changes; no fixed point count is guaranteed to be adequate for every design. See the GPCM scope vignette for a same-data example and its sampling limitations.

Examples

# \donttest{
toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(
  toy, "Person", c("Rater", "Criterion"), "Score",
  method = "MML", model = "RSM",
  quad_points = 31
)
sensitivity <- mml_quadrature_sensitivity(
  fit, toy, quad_points = c(31, 41), adaptive_quad_points = c(31, 61)
)
summary(sensitivity)
#> RSM-MML quadrature sensitivity summary
#>  ReferenceNodes ComparedGrids AllEstimationConverged AllHessiansFullRank
#>              31             2                   TRUE                TRUE
#>  MaxNLLAbsChangePerPerson MaxMeasurementParameterAbsChange MaxSlopeAbsChange
#>                   0.00039                          0.00215                NA
#>  MaxPopulationSDAbsChange MaxProbabilityAbsChange MaxEAPAbsChange
#>                         0                 0.00072         0.00756
#>  MaxPosteriorSDAbsChange
#>                  0.01155
#> 
#> Grid comparisons
#>  Model ReferenceNodes Nodes IsReference NLLChangePerPerson
#>    RSM             31    31        TRUE            0.00000
#>    RSM             31    41       FALSE            0.00039
#>  NLLAbsChangePerPerson MeasurementParameterMaxAbsChange SlopeMaxAbsChange
#>                0.00000                          0.00000                NA
#>                0.00039                          0.00215                NA
#>  RawSlopeSEMaxAbsChange SlopeIntervalMaxAbsChange
#>                      NA                        NA
#>                      NA                        NA
#>  SlopeIntervalEligibilityChanged PopulationSDAbsChange
#>                               NA                     0
#>                               NA                     0
#>  RawPopulationSDSEAbsChange ProbabilityMaxAbsChange EAPMaxAbsChange
#>                          NA                 0.00000         0.00000
#>                          NA                 0.00072         0.00756
#>  PosteriorSDMaxAbsChange
#>                  0.00000
#>                  0.01155
#> 
#> Fixed-parameter integration review (adaptive minus fixed)
#>  FixedNodes AdaptiveNodes Persons Unavailable MaxAbsLogMarginalChange
#>          31            31      48           0             0.010239937
#>          41            31      48           0             0.002018021
#>          31            61      48           0             0.010239937
#>          41            61      48           0             0.002018021
#>  MaxAbsEAPChange MaxAbsSDChange
#>      0.009191803    0.015226750
#>      0.002018215    0.003787628
#>      0.009191803    0.015226750
#>      0.002018215    0.003787628
#> Inspect $quadrature_review for adaptive-order changes and unavailable rows.
#> No automatic stability classification or readiness change is applied.
# Preserve small numerical differences when preparing the sensitivity table.
apa_table(sensitivity, digits = 5)
#>  Model ReferenceNodes Nodes IsReference NLLChangePerPerson
#>    RSM             31    31        TRUE            0.00000
#>    RSM             31    41       FALSE            0.00039
#>  NLLAbsChangePerPerson MeasurementParameterMaxAbsChange SlopeMaxAbsChange
#>                0.00000                          0.00000                NA
#>                0.00039                          0.00215                NA
#>  RawSlopeSEMaxAbsChange SlopeIntervalMaxAbsChange
#>                      NA                        NA
#>                      NA                        NA
#>  SlopeIntervalEligibilityChanged PopulationSDAbsChange
#>                               NA                     0
#>                               NA                     0
#>  RawPopulationSDSEAbsChange ProbabilityMaxAbsChange EAPMaxAbsChange
#>                          NA                 0.00000         0.00000
#>                          NA                 0.00072         0.00756
#>  PosteriorSDMaxAbsChange
#>                  0.00000
#>                  0.01155
# }