mfrmr Linking and DFF Guide

Package-native guide to checking connectedness, building anchor-based links, monitoring drift, and screening differential facet functioning (DFF) in mfrmr.

Start with the linking question

• "Is the design connected enough to support a common scale?" Use subset_connectivity_report() and plot(..., type = "design_matrix").

• "Which elements can I export as anchors from an existing fit?" Use make_anchor_table() and audit_mfrm_anchors().

• "How do I anchor a new administration to a baseline?" Use anchor_to_baseline().

• "Have common elements drifted across separately fitted waves?" Use detect_anchor_drift() and plot_anchor_drift().

• "Do specific facet levels function differently across groups?" Use analyze_dff() and plot_dif_heatmap().

Recommended linking route

1. Fit with fit_mfrm() and diagnose with diagnose_mfrm().

2. Check connectedness with subset_connectivity_report().

3. Build or audit anchors with make_anchor_table() and audit_mfrm_anchors().

4. Use anchor_to_baseline() when you need to place raw new data onto a baseline scale.

5. Use build_equating_chain() only as a screened linking aid across already fitted waves.

6. Use detect_anchor_drift() for stability monitoring on separately fitted waves.

7. Run analyze_dff() only after checking connectivity and common-scale evidence.

Which helper answers which task

subset_connectivity_report()

Summarizes connected subsets, bottleneck facets, and design-matrix coverage.

make_anchor_table()

Extracts reusable anchor candidates from a fit.

anchor_to_baseline()

Anchors new raw data to a baseline fit and returns anchored diagnostics plus a consistency check against the baseline scale.

detect_anchor_drift()

Compares fitted waves directly to flag unstable anchor elements.

build_equating_chain()

Accumulates screened pairwise links across a series of administrations or forms.

analyze_dff()

Screens differential facet functioning with residual or refit methods, using screening-only language unless linking and precision support stronger interpretation.

Practical linking rules

• Check connectedness before interpreting subgroup or wave differences.

• Use DFF outputs as screening results when common-scale linking is weak.

• Treat drift flags as prompts for review, not automatic evidence that an anchor must be removed.

• Treat LinkSupportAdequate = FALSE as a weak-link warning: at least one linking facet retained fewer than 5 common elements after screening.

• Rebuild anchors from a defensible baseline rather than chaining unstable links by hand.

Typical workflow

• Cross-sectional linkage review: fit_mfrm() -> diagnose_mfrm() -> subset_connectivity_report() -> plot(..., type = "design_matrix").

• Baseline placement review: make_anchor_table() -> anchor_to_baseline() -> diagnose_mfrm().

• Multi-wave drift review: fit each wave separately -> detect_anchor_drift() -> plot_anchor_drift().

• Group comparison route: subset_connectivity_report() -> analyze_dff() -> dif_report() -> plot_dif_heatmap().

Companion guides

• For visual follow-up, see mfrmr_visual_diagnostics.

• For report/table selection, see mfrmr_reports_and_tables.

• For end-to-end routes, see mfrmr_workflow_methods.

• For a longer walkthrough, see vignette("mfrmr-linking-and-dff", package = "mfrmr").

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(
  toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "JML",
  maxit = 10
)
#> Warning: Optimizer did not fully converge (code = 1). Consider increasing maxit (current: 10) or relaxing reltol (current: 1e-06).
diag <- diagnose_mfrm(fit, residual_pca = "none")

subsets <- subset_connectivity_report(fit, diagnostics = diag)
subsets$summary[, c("Subset", "Observations", "ObservationPercent")]
#>   Subset Observations ObservationPercent
#> 1      1          384                100

dff <- analyze_dff(fit, diag, facet = "Rater", group = "Group", data = toy)
head(dff$dif_table[, c("Level", "Group1", "Group2", "Classification")])
#> # A tibble: 4 × 4
#>   Level Group1 Group2 Classification 
#>   <chr> <chr>  <chr>  <chr>          
#> 1 R01   A      B      Screen negative
#> 2 R02   A      B      Screen negative
#> 3 R03   A      B      Screen negative
#> 4 R04   A      B      Screen negative