Run a legacy-compatible estimation workflow wrapper

This helper mirrors mfrmRFacets.R behavior as a package API and keeps legacy-compatible defaults (model = "RSM", method = "JML"), while allowing users to choose compatible estimation options.

Usage

run_mfrm_facets(
  data,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  keep_original = FALSE,
  model = c("RSM", "PCM"),
  method = c("JML", "JMLE", "MML"),
  step_facet = NULL,
  anchors = NULL,
  group_anchors = NULL,
  noncenter_facet = "Person",
  dummy_facets = NULL,
  positive_facets = NULL,
  quad_points = 15,
  maxit = 400,
  reltol = 1e-06,
  top_n_interactions = 20L
)

mfrmRFacets(
  data,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  keep_original = FALSE,
  model = c("RSM", "PCM"),
  method = c("JML", "JMLE", "MML"),
  step_facet = NULL,
  anchors = NULL,
  group_anchors = NULL,
  noncenter_facet = "Person",
  dummy_facets = NULL,
  positive_facets = NULL,
  quad_points = 15,
  maxit = 400,
  reltol = 1e-06,
  top_n_interactions = 20L
)

Arguments

data: A data.frame in long format.
person: Optional person column name. If NULL, guessed from names.
facets: Optional facet column names. If NULL, inferred from remaining columns after person/score/weight mapping.
score: Optional score column name. If NULL, guessed from names.
weight: Optional weight column name.
keep_original: Passed to fit_mfrm().
model: MFRM model ("RSM" default, or "PCM").
method: Estimation method ("JML" default; "JMLE" and "MML" also supported).
step_facet: Step facet for PCM mode; passed to fit_mfrm().
anchors: Optional anchor table (data.frame).
group_anchors: Optional group-anchor table (data.frame).
noncenter_facet: Non-centered facet passed to fit_mfrm().
dummy_facets: Optional dummy facets fixed at zero.
positive_facets: Optional facets with positive orientation.
quad_points: Quadrature points for MML; passed to fit_mfrm().
maxit: Maximum optimizer iterations.
reltol: Optimization tolerance.
top_n_interactions: Number of rows for interaction diagnostics.

Value

A list with components:

fit: fit_mfrm() result
diagnostics: diagnose_mfrm() result
iteration: estimation_iteration_report() result
fair_average: fair_average_table() result
rating_scale: rating_scale_table() result
run_info: run metadata table
mapping: resolved column mapping

Details

run_mfrm_facets() is intended as a one-shot workflow helper: fit -> diagnostics -> key report tables. Returned objects can be inspected with summary() and plot().

Estimation-method notes

method = "JML" (default): legacy-compatible joint estimation route.
method = "JMLE": explicit JMLE label; internally equivalent to JML route.
method = "MML": marginal maximum likelihood route using quad_points.

model = "PCM" is supported; set step_facet when facet-specific step structure is needed.

Visualization

plot(out, type = "fit") delegates to plot.mfrm_fit() and returns fit-level visual bundles (e.g., Wright/pathway/CCC).
plot(out, type = "qc") delegates to plot_qc_dashboard() and returns a QC dashboard plot object.

Interpreting output

Start with summary(out):

check convergence and iteration count in overview.
confirm resolved columns in mapping.

Then inspect:

out$rating_scale for category/threshold behavior.
out$fair_average for observed-vs-model scoring tendencies.
out$diagnostics for misfit/reliability/interactions.

Typical workflow

Run run_mfrm_facets() with explicit column mapping.
Check summary(out) and summary(out$diagnostics).
Visualize with plot(out, type = "fit") and plot(out, type = "qc").
Export selected tables for reporting (out$rating_scale, out$fair_average).

Preferred route for new analyses

For new scripts, prefer the package-native route: fit_mfrm() -> diagnose_mfrm() -> reporting_checklist() -> build_apa_outputs(). Use run_mfrm_facets() when you specifically need the legacy-compatible one-shot wrapper.

Examples

toy <- load_mfrmr_data("example_core")
toy_small <- toy[toy$Person %in% unique(toy$Person)[1:12], , drop = FALSE]

# Legacy-compatible default: RSM + JML
out <- run_mfrm_facets(
  data = toy_small,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  maxit = 6
)
#> Warning: Optimizer did not fully converge (code = 1). Consider increasing maxit (current: 6) or relaxing reltol (current: 1e-06).
names(out)
#> [1] "fit"          "diagnostics"  "iteration"    "fair_average" "rating_scale"
#> [6] "run_info"     "mapping"     
out$fit$summary[, c("Model", "Method")]
#> # A tibble: 1 × 2
#>   Model Method
#>   <chr> <chr> 
#> 1 RSM   JMLE  
s <- summary(out)
s$overview[, c("Model", "Method", "Converged")]
#> # A tibble: 1 × 3
#>   Model Method Converged
#>   <chr> <chr>  <lgl>    
#> 1 RSM   JMLE   FALSE    
p_fit <- plot(out, type = "fit", draw = FALSE)
class(p_fit)
#> [1] "mfrm_plot_bundle" "list"            

# Optional: MML route
if (interactive()) {
  out_mml <- run_mfrm_facets(
    data = toy_small,
    person = "Person",
    facets = c("Rater", "Criterion"),
    score = "Score",
    method = "MML",
    quad_points = 5,
    maxit = 6
  )
  out_mml$fit$summary[, c("Model", "Method")]
}