Type:	Package
Title:	Estimation and Diagnostics for Many-Facet Measurement Models
Version:	0.1.4
Description:	Fits many-facet measurement models and returns diagnostics, reporting helpers, and reproducible analysis bundles using a native R implementation. Supports arbitrary facet counts, rating-scale and partial-credit parameterizations ('Andrich' (1978) <doi:10.1007/BF02293814>; 'Masters' (1982) <doi:10.1007/BF02296272>), marginal maximum likelihood estimation via the EM algorithm ('Bock' and 'Aitkin' (1981) <doi:10.1007/BF02293801>) and joint maximum likelihood estimation, plus tools for anchor review, interaction screening, linking workflows, and publication-ready summaries.
URL:	https://ryuya-dot-com.github.io/R_package_mfrmr/, https://github.com/Ryuya-dot-com/R_package_mfrmr
BugReports:	https://github.com/Ryuya-dot-com/R_package_mfrmr/issues
License:	MIT + file LICENSE
Language:	en
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1)
Imports:	dplyr, tidyr, tibble, purrr, stringr, psych, lifecycle, rlang, stats, utils
Suggests:	testthat (≥ 3.0.0), covr, knitr, rmarkdown
VignetteBuilder:	knitr
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-03-26 12:40:49 UTC; Kyomuron
Author:	Ryuya Komuro [aut, cre]
Maintainer:	Ryuya Komuro <ryuya.komuro.c4@tohoku.ac.jp>
Repository:	CRAN
Date/Publication:	2026-03-30 19:20:02 UTC

mfrmr: Many-Facet Rasch Modeling in R

Description

mfrmr provides estimation, diagnostics, and reporting utilities for many-facet Rasch models (MFRM) using a native R implementation.

Details

Recommended workflow:

1. Fit model with fit_mfrm()

2. Compute diagnostics with diagnose_mfrm()

3. Run residual PCA with analyze_residual_pca() if needed

4. Estimate interactions with estimate_bias()

5. Build narrative/report outputs with build_apa_outputs() and build_visual_summaries()

Guide pages:

• mfrmr_workflow_methods

• mfrmr_visual_diagnostics

• mfrmr_reports_and_tables

• mfrmr_reporting_and_apa

• mfrmr_linking_and_dff

• mfrmr_compatibility_layer

Companion vignettes:

• vignette("mfrmr-workflow", package = "mfrmr")

• vignette("mfrmr-visual-diagnostics", package = "mfrmr")

• vignette("mfrmr-reporting-and-apa", package = "mfrmr")

• vignette("mfrmr-linking-and-dff", package = "mfrmr")

Function families:

• Model fitting: fit_mfrm(), summary.mfrm_fit(), plot.mfrm_fit()

• Legacy-compatible workflow wrapper: run_mfrm_facets(), mfrmRFacets()

• Diagnostics: diagnose_mfrm(), summary(diag), analyze_residual_pca(), plot_residual_pca()

• Bias and interaction: estimate_bias(), estimate_all_bias(), summary(bias), bias_interaction_report(), plot_bias_interaction()

• Differential functioning: analyze_dff(), analyze_dif(), dif_interaction_table(), plot_dif_heatmap(), dif_report()

• Design simulation: build_mfrm_sim_spec(), extract_mfrm_sim_spec(), simulate_mfrm_data(), evaluate_mfrm_design(), evaluate_mfrm_signal_detection(), predict_mfrm_population(), predict_mfrm_units(), sample_mfrm_plausible_values() (including fit-derived empirical / resampled / skeleton-based simulation specifications; fixed-calibration unit scoring currently requires method = "MML")

• Reporting: build_apa_outputs(), build_visual_summaries(), reporting_checklist(), apa_table()

• Dashboards: facet_quality_dashboard(), plot_facet_quality_dashboard()

• Export / reproducibility: build_mfrm_manifest(), build_mfrm_replay_script(), export_mfrm_bundle()

• Equivalence: analyze_facet_equivalence(), plot_facet_equivalence()

• Data and anchors: describe_mfrm_data(), audit_mfrm_anchors(), make_anchor_table(), load_mfrmr_data()

Data interface:

• Input analysis data is long format (one row per observed rating).

• Packaged simulation data is available via load_mfrmr_data() or data().

Interpreting output

Core object classes are:

• mfrm_fit: fitted model parameters and metadata.

• mfrm_diagnostics: fit/reliability/flag diagnostics.

• mfrm_bias: interaction bias estimates.

• mfrm_dff / mfrm_dif: differential-functioning contrasts and screening summaries.

• mfrm_population_prediction: scenario-level forecast summaries for one future design.

• mfrm_unit_prediction: fixed-calibration posterior summaries for future or partially observed persons.

• mfrm_plausible_values: approximate fixed-calibration posterior draws for future or partially observed persons.

• mfrm_bundle families: summary/report bundles and plotting payloads.

Typical workflow

1. Prepare long-format data.

2. Fit with fit_mfrm().

3. Diagnose with diagnose_mfrm().

4. Run analyze_dff() or estimate_bias() when fairness or interaction questions matter.

5. Report with build_apa_outputs() and build_visual_summaries().

6. For design planning, move to build_mfrm_sim_spec(), evaluate_mfrm_design(), and predict_mfrm_population().

7. For future-unit scoring, refit or retain an MML calibration and then use predict_mfrm_units() or sample_mfrm_plausible_values().

Model formulation

The many-facet Rasch model (MFRM; Linacre, 1989) extends the basic Rasch model by incorporating multiple measurement facets into a single linear model on the log-odds scale.

General MFRM equation

For an observation where person n with ability \theta_n is rated by rater j with severity \delta_j on criterion i with difficulty \beta_i, the probability of observing category k (out of K ordered categories) is:

P(X_{nij} = k \mid \theta_n, \delta_j, \beta_i, \tau) = \frac{\exp\bigl[\sum_{s=1}^{k}(\theta_n - \delta_j - \beta_i - \tau_s)\bigr]} {\sum_{c=0}^{K}\exp\bigl[\sum_{s=1}^{c}(\theta_n - \delta_j - \beta_i - \tau_s)\bigr]}

where \tau_s are the Rasch-Andrich threshold (step) parameters and \sum_{s=1}^{0}(\cdot) \equiv 0 by convention. Additional facets enter as additive terms in the linear predictor \eta = \theta_n - \delta_j - \beta_i - \ldots.

This formulation generalises to any number of facets; the facets argument to fit_mfrm() accepts an arbitrary-length character vector.

Rating Scale Model (RSM)

Under the RSM (Andrich, 1978), all levels of the step facet share a single set of threshold parameters \tau_1, \ldots, \tau_K.

Partial Credit Model (PCM)

Under the PCM (Masters, 1982), each level of the designated step_facet has its own threshold vector on the package's common observed score scale. In the current implementation, threshold locations may vary by step-facet level, but the fitted score range is still defined by one global category set taken from the observed data.

Estimation methods

Marginal Maximum Likelihood (MML)

MML integrates over the person ability distribution using Gauss-Hermite quadrature (Bock & Aitkin, 1981):

L = \prod_{n} \int P(\mathbf{X}_n \mid \theta, \boldsymbol{\delta}) \, \phi(\theta) \, d\theta \approx \prod_{n} \sum_{q=1}^{Q} w_q \, P(\mathbf{X}_n \mid \theta_q, \boldsymbol{\delta})

where \phi(\theta) is the assumed normal prior and (\theta_q, w_q) are quadrature nodes and weights. Person estimates are obtained post-hoc via Expected A Posteriori (EAP):

\hat{\theta}_n^{\mathrm{EAP}} = \frac{\sum_q \theta_q \, w_q \, L(\mathbf{X}_n \mid \theta_q)} {\sum_q w_q \, L(\mathbf{X}_n \mid \theta_q)}

MML avoids the incidental-parameter problem and is generally preferred for smaller samples.

Joint Maximum Likelihood (JML/JMLE)

JMLE estimates all person and facet parameters simultaneously as fixed effects by maximising the joint log-likelihood \ell(\boldsymbol{\theta}, \boldsymbol{\delta} \mid \mathbf{X}) directly. It does not assume a parametric person distribution, which can be advantageous when the population shape is strongly non-normal, but parameter estimates are known to be biased when the number of persons is small relative to the number of items (Neyman & Scott, 1948).

See fit_mfrm() for practical guidance on choosing between the two.

Statistical background

Key statistics reported throughout the package:

Infit (Information-Weighted Mean Square)

Weighted average of squared standardized residuals, where weights are the model-based variance of each observation:

\mathrm{Infit}_j = \frac{\sum_i Z_{ij}^2 \, \mathrm{Var}_i \, w_i} {\sum_i \mathrm{Var}_i \, w_i}

Expected value is 1.0 under model fit. Values below 0.5 suggest overfit (Mead-style responses); values above 1.5 suggest underfit (noise or misfit). Infit is most sensitive to unexpected patterns among on-target observations (Wright & Masters, 1982).

Note: The 0.5–1.5 range is a widely used rule of thumb (Bond & Fox, 2015). Acceptable ranges may differ by context: 0.6–1.4 for high-stakes testing; 0.7–1.3 for clinical instruments; up to 0.5–1.7 for surveys and exploratory work (Linacre, 2002).

Outfit (Unweighted Mean Square)

Simple average of squared standardized residuals:

\mathrm{Outfit}_j = \frac{\sum_i Z_{ij}^2 \, w_i}{\sum_i w_i}

Same expected value and flagging thresholds as Infit, but more sensitive to extreme off-target outliers (e.g., a high-ability person scoring the lowest category).

ZSTD (Standardized Fit Statistic)

Wilson-Hilferty cube-root transformation that converts the mean-square chi-square ratio to an approximate standard normal deviate:

\mathrm{ZSTD} = \frac{\mathrm{MnSq}^{1/3} - (1 - 2/(9\,\mathit{df}))} {\sqrt{2/(9\,\mathit{df})}}

Values near 0 indicate expected fit; |\mathrm{ZSTD}| > 2 flags potential misfit at the 5\ 1\ Infit and Outfit value.

PTMEA (Point-Measure Correlation)

Pearson correlation between observed scores and estimated person measures within each facet level. Positive values indicate that scoring aligns with the latent trait dimension; negative values suggest reversed orientation or scoring errors.

Separation

Package-reported separation is the ratio of adjusted true standard deviation to root-mean-square measurement error:

G = \frac{\mathrm{SD}_{\mathrm{adj}}}{\mathrm{RMSE}}

where \mathrm{SD}_{\mathrm{adj}} = \sqrt{\mathrm{ObservedVariance} - \mathrm{ErrorVariance}}. Higher values indicate the facet discriminates more statistically distinct levels along the measured variable. In mfrmr, Separation is the model-based value and RealSeparation provides a more conservative companion based on RealSE.

Reliability

R = \frac{G^2}{1 + G^2}

Analogous to Cronbach's alpha or KR-20 for the reproducibility of element ordering. In mfrmr, Reliability is the model-based value and RealReliability gives the conservative companion based on RealSE. For MML, these are anchored to observed-information ModelSE estimates for non-person facets; JML keeps them as exploratory summaries.

Strata

Number of statistically distinguishable groups of elements:

H = \frac{4G + 1}{3}

Three or more strata are commonly used as a practical target (Wright & Masters, 1982), but in this package the estimate inherits the same approximation limits as the separation index.

Key references

• Andrich, D. (1978). A rating formulation for ordered response categories. Psychometrika, 43, 561–573.

• Bond, T. G., & Fox, C. M. (2015). Applying the Rasch model (3rd ed.). Routledge.

• Linacre, J. M. (1989). Many-facet Rasch measurement. MESA Press.

• Linacre, J. M. (2002). What do Infit and Outfit, mean-square and standardized mean? Rasch Measurement Transactions, 16(2), 878.

• Masters, G. N. (1982). A Rasch model for partial credit scoring. Psychometrika, 47, 149–174.

• Wright, B. D., & Masters, G. N. (1982). Rating scale analysis. MESA Press.

• Wright, B. D., & Linacre, J. M. (1994). Reasonable mean-square fit values. Rasch Measurement Transactions, 8(3), 370.

Model selection

RSM vs PCM

The Rating Scale Model (RSM; Andrich, 1978) assumes all levels of the step facet share identical threshold parameters. The Partial Credit Model (PCM; Masters, 1982) allows each level of the step_facet to have its own set of thresholds on the package's shared observed score scale. Use RSM when the rating rubric is identical across all items/criteria; use PCM when category boundaries are expected to vary by item or criterion. In the current implementation, PCM still assumes one common observed score support across the fitted data, so it should not be described as a fully mixed-category model with arbitrary item-specific category counts.

MML vs JML

Marginal Maximum Likelihood (MML) integrates over the person ability distribution using Gauss-Hermite quadrature and does not directly estimate person parameters; person estimates are computed post-hoc via Expected A Posteriori (EAP). Joint Maximum Likelihood (JML/JMLE) estimates all person and facet parameters simultaneously as fixed effects.

MML is generally preferred for smaller samples because it avoids the incidental-parameter problem of JML. JML is faster and does not assume a normal person distribution, which may be an advantage when the population shape is strongly non-normal.

See fit_mfrm() for usage.

Author(s)

Maintainer: Ryuya Komuro ryuya.komuro.c4@tohoku.ac.jp (ORCID)

See Also

Useful links:

• https://ryuya-dot-com.github.io/R_package_mfrmr/

• https://github.com/Ryuya-dot-com/R_package_mfrmr

• Report bugs at https://github.com/Ryuya-dot-com/R_package_mfrmr/issues

Examples

mfrm_threshold_profiles()
list_mfrmr_data()

Differential facet functioning analysis

Description

Tests whether the difficulty of facet levels differs across a grouping variable (e.g., whether rater severity differs for male vs. female examinees, or whether item difficulty differs across rater subgroups).

analyze_dif() is retained for compatibility with earlier package versions. In many-facet workflows, prefer analyze_dff() as the primary entry point.

Usage

analyze_dff(
  fit,
  diagnostics,
  facet,
  group,
  data = NULL,
  focal = NULL,
  method = c("residual", "refit"),
  min_obs = 10,
  p_adjust = "holm"
)

analyze_dif(...)

Arguments

Details

Differential facet functioning (DFF) occurs when the difficulty or severity of a facet element differs across subgroups of the population, after controlling for overall ability. In an MFRM context this generalises classical DIF (which applies to items) to any facet: raters, criteria, tasks, etc.

Differential functioning is a threat to measurement fairness: if Criterion 1 is harder for Group A than Group B at the same ability level, the measurement scale is no longer group-invariant.

Two methods are available:

Residual method (method = "residual"): Uses the existing fitted model's observation-level residuals. For each facet-level \times group cell, the observed and expected score sums are aggregated and a standardized residual is computed as:

z = \frac{\sum (X_{obs} - E_{exp})}{\sqrt{\sum \mathrm{Var}}}

Pairwise contrasts between groups compare the mean observed-minus-expected difference for each facet level, with uncertainty summarized by a Welch/Satterthwaite approximation. This method is fast, stable with small subsets, and does not require re-estimation. Because the resulting contrast is not a logit-scale parameter difference, the residual method is treated as a screening procedure rather than an ETS-style classifier.

Refit method (method = "refit"): Subsets the data by group, refits the MFRM model within each subset, anchors all non-target facets back to the baseline calibration when possible, and compares the resulting facet-level estimates using a Welch t-statistic:

t = \frac{\hat{\delta}_1 - \hat{\delta}_2} {\sqrt{SE_1^2 + SE_2^2}}

This provides group-specific parameter estimates on a common scale when linking anchors are available, but is slower and may encounter convergence issues with small subsets. ETS categories are reported only for contrasts whose subgroup calibrations retained enough linking anchors to support a common-scale interpretation and whose subgroup precision remained on the package's model-based MML path.

When facet refers to an item-like facet (for example Criterion), this recovers the familiar DIF case. When facet refers to raters or prompts/tasks, the same machinery supports DRF/DPF-style analyses.

For the refit method only, effect size is classified following the ETS (Educational Testing Service) DIF guidelines when subgroup calibrations are both linked and eligible for model-based inference:

• A (Negligible): |\Delta| < 0.43 logits

• B (Moderate): 0.43 \le |\Delta| < 0.64 logits

• C (Large): |\Delta| \ge 0.64 logits

Multiple comparisons are adjusted using Holm's step-down procedure by default, which controls the family-wise error rate without assuming independence. Alternative methods (e.g., "BH" for false discovery rate) can be specified via p_adjust.

Value

An object of class mfrm_dff (with compatibility class mfrm_dif) with:

• dif_table: data.frame of differential-functioning contrasts.

• cell_table: (residual method) per-cell detail table.

• summary: counts by screening or ETS classification.

• group_fits: (refit method) per-group facet estimates.

• config: list with facet, group, method, min_obs, p_adjust settings.

Choosing a method

In most first-pass DFF screening, start with method = "residual". It is faster, reuses the fitted model, and is less fragile in smaller subsets. Use method = "refit" when you specifically want group-specific parameter estimates and can tolerate extra computation. Both methods should yield similar conclusions when sample sizes are adequate (N \ge 100 per group is a useful guideline for stable differential-functioning detection).

Interpreting output

• ⁠$dif_table⁠: one row per facet-level x group-pair with contrast, SE, t-statistic, p-value, adjusted p-value, effect metric, and method-appropriate classification. Includes Method, N_Group1, N_Group2, EffectMetric, ClassificationSystem, ContrastBasis, SEBasis, StatisticLabel, ProbabilityMetric, DFBasis, ReportingUse, PrimaryReportingEligible, and sparse columns.

• ⁠$cell_table⁠: (residual method only) per-cell detail with N, ObsScore, ExpScore, ObsExpAvg, StdResidual.

• ⁠$summary⁠: counts by screening result (method = "residual") or ETS category plus linked-screening and insufficient-linking rows (method = "refit").

• ⁠$group_fits⁠: (refit method only) list of per-group facet estimates and subgroup linking diagnostics.

Typical workflow

1. Fit a model with fit_mfrm().

2. Run analyze_dff(fit, diagnostics, facet = "Criterion", group = "Gender", data = my_data).

3. Inspect ⁠$dif_table⁠ for flagged levels and ⁠$summary⁠ for counts.

4. Use dif_interaction_table() when you need cell-level diagnostics.

5. Use plot_dif_heatmap() or dif_report() for communication.

See Also

fit_mfrm(), estimate_bias(), compare_mfrm(), dif_interaction_table(), plot_dif_heatmap(), dif_report(), subset_connectivity_report(), mfrmr_linking_and_dff

Examples

toy <- load_mfrmr_data("example_bias")

fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
dff <- analyze_dff(fit, diag, facet = "Rater", group = "Group", data = toy)
dff$summary
head(dff$dif_table[, c("Level", "Group1", "Group2", "Contrast", "Classification")])
sc <- subset_connectivity_report(fit, diagnostics = diag)
plot(sc, type = "design_matrix", draw = FALSE)
if ("ScaleLinkStatus" %in% names(dff$dif_table)) {
  unique(dff$dif_table$ScaleLinkStatus)
}

Analyze practical equivalence within a facet

Description

Analyze practical equivalence within a facet

Usage

analyze_facet_equivalence(
  fit,
  diagnostics = NULL,
  facet = NULL,
  equivalence_bound = 0.5,
  conf_level = 0.95
)

Arguments

Details

This function tests whether facet elements (e.g., raters) are similar enough to be treated as practically interchangeable, rather than merely testing whether they differ significantly. This is the key distinction from a standard chi-square heterogeneity test: absence of evidence for difference is not evidence of equivalence.

The function uses existing facet estimates and their standard errors from diagnostics$measures; no re-estimation is performed.

The bundle combines four complementary views:

1. Fixed chi-square test: tests H_0: all element measures are equal. A non-significant result is necessary but not sufficient for interchangeability. It is reported as context, not as direct evidence of equivalence.

2. Pairwise TOST (Two One-Sided Tests): for each pair of elements, tests whether the difference falls within \pmequivalence_bound. The TOST procedure (Schuirmann, 1987) rejects the null hypothesis of non-equivalence when both one-sided tests are significant at level \alpha. A pair is declared "Equivalent" when the TOST p-value < 0.05.

3. BIC-based Bayes-factor heuristic: an approximate screening tool (not full Bayesian inference) that compares the evidence for a common-facet model (all elements equal) against a heterogeneity model (elements differ). Values > 3 favour the common-facet model; < 1/3 favour heterogeneity.

4. ROPE-style grand-mean proximity: the proportion of each element's normal-approximation confidence distribution that falls within \pmequivalence_bound of the weighted grand mean. This is a descriptive proximity summary, not a Bayesian ROPE decision rule around a prespecified null value.

Choosing equivalence_bound: the default of 0.5 logits is a moderate criterion. For high-stakes certification, 0.3 logits may be appropriate; for exploratory or low-stakes contexts, 1.0 logits may suffice. The bound should reflect the smallest difference that would be practically meaningful in your application.

Value

A named list with class mfrm_facet_equivalence.

What this analysis means

analyze_facet_equivalence() is a practical-interchangeability screen. It asks whether facet levels are close enough, under a user-defined logit bound, to be treated as practically similar for the current use case.

What this analysis does not justify

• A non-significant chi-square result is not evidence of equivalence.

• Forest/ROPE displays are descriptive and do not replace the pairwise TOST decision rule.

• The BIC-based Bayes-factor summary is a heuristic screen, not a full Bayesian equivalence analysis.

Interpreting output

Start with summary$Decision, which is a conservative summary of the pairwise TOST results. Then use the remaining tables as context:

• chi_square: is there broad heterogeneity in the facet?

• pairwise: which specific pairs meet the practical-equivalence bound?

• rope / forest: how close is each level to the facet grand mean?

Smaller equivalence_bound values make the criterion stricter. If the decision is "partial_pairwise_equivalence", that means some pairwise contrasts satisfy the practical-equivalence bound but not all of them do.

Decision rule

The final Decision is a pairwise TOST summary rather than a global equivalence proof. If all pairwise contrasts satisfy the practical- equivalence bound, the facet is labeled "all_pairs_equivalent". If at least one, but not all, pairwise contrasts are equivalent, the facet is labeled "partial_pairwise_equivalence". If no pairwise contrasts meet the practical-equivalence bound, the facet is labeled "no_pairwise_equivalence_established". The chi-square, Bayes-factor, and grand-mean proximity summaries are reported as descriptive context.

How to read the main outputs

• summary: one-row pairwise-TOST decision summary and aggregate context.

• pairwise: pair-level TOST detail; use this for the primary inferential read.

• chi_square: broad heterogeneity screen.

• rope / forest: level-wise proximity to the weighted grand mean.

Recommended next step

If the result is borderline or high-stakes, re-run the analysis with a tighter or looser equivalence_bound, then inspect pairwise and plot_facet_equivalence() before deciding how strongly to claim interchangeability.

Typical workflow

1. Fit a model with fit_mfrm().

2. Run analyze_facet_equivalence() for the facet you want to screen.

3. Read summary and chi_square first.

4. Use plot_facet_equivalence() to inspect which levels drive the result.

Output

The returned bundle has class mfrm_facet_equivalence and includes:

• summary: one-row overview with convergent decision

• chi_square: fixed chi-square / separation summary

• pairwise: pairwise TOST detail table

• rope: element-wise ROPE probabilities around the weighted grand mean

• forest: element-wise estimate, confidence interval, and ROPE status

• settings: applied facet and threshold settings

See Also

facets_chisq_table(), fair_average_table(), plot_facet_equivalence()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 25)
eq <- analyze_facet_equivalence(fit, facet = "Rater")
eq$summary[, c("Facet", "Elements", "Decision", "MeanROPE")]
head(eq$pairwise[, c("ElementA", "ElementB", "Equivalent")])

Run exploratory residual PCA summaries

Description

Legacy-compatible residual diagnostics can be inspected in two ways:

1. overall residual PCA on the person x combined-facet matrix

2. facet-specific residual PCA on person x facet-level matrices

Usage

analyze_residual_pca(
  diagnostics,
  mode = c("overall", "facet", "both"),
  facets = NULL,
  pca_max_factors = 10L
)

Arguments

Details

The function works on standardized residual structures derived from diagnose_mfrm(). When a fitted object from fit_mfrm() is supplied, diagnostics are computed internally.

Conceptually, this follows the Rasch residual-PCA tradition of examining structure in model residuals after the primary Rasch dimension has been extracted. In mfrmr, however, the implementation is an exploratory many-facet adaptation: it works on standardized residual matrices built as person x combined-facet or person x facet-level layouts, rather than reproducing FACETS/Winsteps residual-contrast tables one-to-one.

Output tables use:

• Component: principal-component index (1, 2, ...)

• Eigenvalue: eigenvalue for each component

• Proportion: component variance proportion

• Cumulative: cumulative variance proportion

For mode = "facet" or "both", by_facet_table additionally includes a Facet column.

summary(pca) is supported through summary(). plot(pca) is dispatched through plot() for class mfrm_residual_pca. Available types include "overall_scree", "facet_scree", "overall_loadings", and "facet_loadings".

Value

A named list with:

• mode: resolved mode used for computation

• facet_names: facets analyzed

• overall: overall PCA bundle (or NULL)

• by_facet: named list of facet PCA bundles

• overall_table: variance table for overall PCA

• by_facet_table: stacked variance table across facets

Interpreting output

Use overall_table first:

• early components with noticeably larger eigenvalues or proportions suggest stronger residual structure that may deserve follow-up.

Then inspect by_facet_table:

• helps localize which facet contributes most to residual structure.

Finally, inspect loadings via plot_residual_pca() to identify which variables/elements drive each component.

References

The residual-PCA idea follows the Rasch residual-structure literature, especially Linacre's discussions of principal components of Rasch residuals. The current mfrmr implementation should be interpreted as an exploratory extension for many-facet workflows rather than as a direct reproduction of a single FACETS/Winsteps output table.

• Linacre, J. M. (1998). Structure in Rasch residuals: Why principal components analysis (PCA)? Rasch Measurement Transactions, 12(2), 636.

• Linacre, J. M. (1998). Detecting multidimensionality: Which residual data-type works best? Journal of Outcome Measurement, 2(3), 266-283.

Typical workflow

1. Fit model and run diagnose_mfrm() with residual_pca = "none" or "both".

2. Call analyze_residual_pca(..., mode = "both").

3. Review summary(pca), then plot scree/loadings.

4. Cross-check with fit/misfit diagnostics before conclusions.

See Also

diagnose_mfrm(), plot_residual_pca(), mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "both")
pca <- analyze_residual_pca(diag, mode = "both")
pca2 <- analyze_residual_pca(fit, mode = "both")
summary(pca)
p <- plot_residual_pca(pca, mode = "overall", plot_type = "scree", draw = FALSE)
class(p)
head(p$data)
head(pca$overall_table)

Fit new data anchored to a baseline calibration

Description

Re-estimates a many-facet Rasch model on new data while holding selected facet parameters fixed at the values from a previous (baseline) calibration. This is the standard workflow for placing new data onto an existing scale, linking test forms, or carrying a baseline calibration across administration windows.

Usage

anchor_to_baseline(
  new_data,
  baseline_fit,
  person,
  facets,
  score,
  anchor_facets = NULL,
  include_person = FALSE,
  weight = NULL,
  model = NULL,
  method = NULL,
  anchor_policy = "warn",
  ...
)

## S3 method for class 'mfrm_anchored_fit'
print(x, ...)

## S3 method for class 'mfrm_anchored_fit'
summary(object, ...)

## S3 method for class 'summary.mfrm_anchored_fit'
print(x, ...)

Arguments

Details

This function automates the baseline-anchored calibration workflow:

1. Extracts anchor values from the baseline fit using make_anchor_table().

2. Re-estimates the model on new_data with those anchors fixed via fit_mfrm(..., anchors = anchor_table).

3. Runs diagnose_mfrm() on the anchored fit.

4. Computes element-level differences (new estimate minus baseline estimate) for every common element.

The model and method arguments default to the baseline fit's settings so the calibration framework remains consistent. Elements present in the anchor table but absent from the new data are handled according to anchor_policy: "warn" (default) emits a message, "error" stops execution, and "silent" ignores silently.

The returned drift table is best interpreted as an anchored consistency check. When a facet is fixed through anchor_facets, those anchored levels are constrained in the new run, so their reported differences are not an independent drift analysis. For genuine cross-wave drift monitoring, fit the waves separately and use detect_anchor_drift() on the resulting fits.

Element-level differences are calculated for every element that appears in both the baseline and the new calibration:

\Delta_e = \hat{\delta}_{e,\text{new}} - \hat{\delta}_{e,\text{base}}

An element is flagged when |\Delta_e| > 0.5 logits or |\Delta_e / SE_{\Delta_e}| > 2.0, where SE_{\Delta_e} = \sqrt{SE_{\mathrm{base}}^2 + SE_{\mathrm{new}}^2}.

Value

Object of class mfrm_anchored_fit with components:

fit

The anchored mfrm_fit object.

diagnostics

Output of diagnose_mfrm() on the anchored fit.

baseline_anchors

Anchor table extracted from the baseline.

drift

Tibble of element-level drift statistics.

Which function should I use?

• Use anchor_to_baseline() when you have one new dataset and want to place it directly on a baseline scale.

• Use detect_anchor_drift() when you already have multiple fitted waves and want to compare their stability.

• Use build_equating_chain() when you need cumulative offsets across an ordered series of waves.

Interpreting output

• ⁠$drift⁠: one row per common element with columns Facet, Level, Baseline, New, Drift, SE_Baseline, SE_New, SE_Diff, Drift_SE_Ratio, and Flag. Read this as an anchored consistency table. Small absolute differences indicate that the anchored re-fit stayed close to the baseline scale. Flagged rows warrant review, but they are not a substitute for a separate drift study on unanchored common elements.

• ⁠$fit⁠: the full anchored mfrm_fit object, usable with diagnose_mfrm(), measurable_summary_table(), etc.

• ⁠$diagnostics⁠: pre-computed diagnostics for the anchored calibration.

• ⁠$baseline_anchors⁠: the anchor table fed to fit_mfrm(), useful for auditing which elements were constrained.

Typical workflow

1. Fit the baseline model: fit1 <- fit_mfrm(...).

2. Collect new data (e.g., a later administration).

3. Call res <- anchor_to_baseline(new_data, fit1, ...).

4. Inspect summary(res) to confirm the anchored run remains close to the baseline scale.

5. For multi-wave drift monitoring, fit waves separately and pass the fits to detect_anchor_drift() or build_equating_chain().

See Also

fit_mfrm(), make_anchor_table(), detect_anchor_drift(), diagnose_mfrm(), build_equating_chain(), mfrmr_linking_and_dff

Examples

d1 <- load_mfrmr_data("study1")
keep1 <- unique(d1$Person)[1:15]
d1 <- d1[d1$Person %in% keep1, , drop = FALSE]
fit1 <- fit_mfrm(d1, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 15)
d2 <- load_mfrmr_data("study2")
keep2 <- unique(d2$Person)[1:15]
d2 <- d2[d2$Person %in% keep2, , drop = FALSE]
res <- anchor_to_baseline(d2, fit1, "Person",
                          c("Rater", "Criterion"), "Score",
                          anchor_facets = "Criterion")
summary(res)
head(res$drift[, c("Facet", "Level", "Drift", "Flag")])
res$baseline_anchors[1:3, ]

Build APA-style table output using base R structures

Description

Build APA-style table output using base R structures

Usage

apa_table(
  x,
  which = NULL,
  diagnostics = NULL,
  digits = 2,
  caption = NULL,
  note = NULL,
  bias_results = NULL,
  context = list(),
  whexact = FALSE,
  branch = c("apa", "facets")
)

Arguments

Details

This helper avoids styling dependencies and returns a reproducible base data.frame plus metadata.

Supported which values:

• For mfrm_fit: "summary", "person", "facets", "steps"

• For diagnostics list: "overall_fit", "measures", "fit", "reliability", "facets_chisq", "bias", "interactions", "interrater_summary", "interrater_pairs", "obs"

• For bias-result list: "table", "summary", "chi_sq"

Value

A list of class apa_table with fields:

• table (data.frame)

• which

• caption

• note

• digits

• branch, style

Interpreting output

• table: plain data.frame ready for export or further formatting.

• which: source component that produced the table.

• caption/note: manuscript-oriented metadata stored with the table.

Typical workflow

1. Build table object with apa_table(...).

2. Inspect quickly with summary(tbl).

3. Render base preview via plot(tbl, ...) or export tbl$table.

See Also

fit_mfrm(), diagnose_mfrm(), build_apa_outputs(), reporting_checklist(), mfrmr_reporting_and_apa

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
tbl <- apa_table(fit, which = "summary", caption = "Model summary", note = "Toy example")
tbl_facets <- apa_table(fit, which = "summary", branch = "facets")
summary(tbl)
p <- plot(tbl, draw = FALSE)
p_facets <- plot(tbl_facets, type = "numeric_profile", draw = FALSE)
if (interactive()) {
  plot(
    tbl,
    type = "numeric_profile",
    main = "APA Table Numeric Profile (Customized)",
    palette = c(numeric_profile = "#2b8cbe", grid = "#d9d9d9"),
    label_angle = 45
  )
}
class(tbl)
tbl$note

Convert mfrm_fit to a tidy data.frame

Description

Returns all facet-level estimates (person and others) in a single tidy data.frame. Useful for quick interactive export: write.csv(as.data.frame(fit), "results.csv").

Usage

## S3 method for class 'mfrm_fit'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

This method is intentionally lightweight: it returns just three columns (Facet, Level, Estimate) so that the result is easy to inspect, join, or write to disk.

Value

A data.frame with columns Facet, Level, Estimate.

Interpreting output

Person estimates are returned with Facet = "Person". All non-person facets are stacked underneath in the same schema.

Typical workflow

1. Fit a model with fit_mfrm().

2. Convert with as.data.frame(fit) for a compact long-format export.

3. Join additional diagnostics later if you need SE or fit statistics.

See Also

fit_mfrm, export_mfrm

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", model = "RSM", maxit = 25)
head(as.data.frame(fit))

Audit and normalize anchor/group-anchor tables

Description

Audit and normalize anchor/group-anchor tables

Usage

audit_mfrm_anchors(
  data,
  person,
  facets,
  score,
  anchors = NULL,
  group_anchors = NULL,
  weight = NULL,
  rating_min = NULL,
  rating_max = NULL,
  keep_original = FALSE,
  min_common_anchors = 5L,
  min_obs_per_element = 30,
  min_obs_per_category = 10,
  noncenter_facet = "Person",
  dummy_facets = NULL
)

Arguments

Details

Anchoring (also called "fixing" or scale linking) constrains selected parameter estimates to pre-specified values, placing the current analysis on a previously established scale. This is essential when comparing results across administrations, linking test forms, or monitoring rater drift over time.

This function applies the same preprocessing and key-resolution rules as fit_mfrm(), but returns an audit object so constraints can be checked before estimation. Running the audit first helps avoid estimation failures caused by misspecified or data-incompatible anchors.

Anchor types:

• Direct anchors fix individual element measures to specific logit values (e.g., Rater R1 anchored at 0.35 logits).

• Group anchors constrain the mean of a set of elements to a target value, allowing individual elements to vary freely around that mean.

• When both types overlap for the same element, the direct anchor takes precedence.

Design checks verify that each anchored element has at least min_obs_per_element weighted observations (default 30) and each score category has at least min_obs_per_category (default 10). These thresholds follow standard Rasch sample-size recommendations (Linacre, 1994).

Value

A list of class mfrm_anchor_audit with:

• anchors: cleaned anchor table used by estimation

• group_anchors: cleaned group-anchor table used by estimation

• facet_summary: counts of levels, constrained levels, and free levels

• design_checks: observation-count checks by level/category

• thresholds: active threshold settings used for recommendations

• issue_counts: issue-type counts

• issues: list of issue tables

• recommendations: package-native anchor guidance strings

Interpreting output

• issue_counts/issues: concrete data or specification problems.

• facet_summary: constraint coverage by facet.

• design_checks: whether anchor targets have enough observations.

• recommendations: action items before estimation.

Typical workflow

1. Build candidate anchors (e.g., with make_anchor_table()).

2. Run audit_mfrm_anchors(...).

3. Resolve issues, then fit with fit_mfrm().

See Also

fit_mfrm(), describe_mfrm_data(), make_anchor_table()

Examples

toy <- load_mfrmr_data("example_core")

anchors <- data.frame(
  Facet = c("Rater", "Rater"),
  Level = c("R1", "R1"),
  Anchor = c(0, 0.1),
  stringsAsFactors = FALSE
)
aud <- audit_mfrm_anchors(
  data = toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  anchors = anchors
)
aud$issue_counts
summary(aud)
p_aud <- plot(aud, draw = FALSE)
class(p_aud)

Build a bias-cell count report

Description

Build a bias-cell count report

Usage

bias_count_table(
  bias_results,
  min_count_warn = 10,
  branch = c("original", "facets"),
  fit = NULL
)

Arguments

Details

This helper summarizes how many observations contribute to each bias-cell estimate and flags sparse cells.

Branch behavior:

• "facets": keeps legacy manual-aligned column labels (Sq, ⁠Observd Count⁠, ⁠Obs-Exp Average⁠, ⁠Model S.E.⁠) for side-by-side comparison with external workflows.

• "original": keeps compact field names (Count, BiasSize, SE) for custom QC workflows and scripting.

Value

A named list with:

• table: cell-level counts with low-count flags

• by_facet: named list of counts aggregated by each interaction facet

• by_facet_a, by_facet_b: first two facet summaries (legacy compatibility)

• summary: one-row summary

• thresholds: applied thresholds

• branch, style: output branch metadata

• fit_overview: optional one-row fit metadata when fit is supplied

Interpreting output

• table: cell-level contribution counts and low-count flags.

• by_facet: sparse-cell structure by each interaction facet.

• summary: overall low-count prevalence.

• fit_overview: optional run context (when fit is supplied).

Low-count cells should be interpreted cautiously because bias-size estimates can become unstable with sparse support.

Typical workflow

1. Estimate bias with estimate_bias().

2. Build bias_count_table(...) in desired branch.

3. Review low-count flags before interpreting bias magnitudes.

Further guidance

For a plot-selection guide and a longer walkthrough, see mfrmr_visual_diagnostics and vignette("mfrmr-visual-diagnostics", package = "mfrmr").

Output columns

The table data.frame contains, in the legacy-compatible branch:

FacetA, FacetB

Interaction facet level identifiers; placeholder names for the two interaction facets.

Sq

Sequential row number.

Observd Count

Number of observations for this cell.

Obs-Exp Average

Observed minus expected average for this cell.

Model S.E.

Standard error of the bias estimate.

Infit, Outfit

Fit statistics for this cell.

LowCountFlag

Logical; TRUE when count < min_count_warn.

The summary data.frame contains:

InteractionFacets

Names of the interaction facets.

Cells, TotalCount

Number of cells and total observations.

LowCountCells, LowCountPercent

Number and share of low-count cells.

See Also

estimate_bias(), unexpected_after_bias_table(), build_fixed_reports(), mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bias <- estimate_bias(fit, diag, facet_a = "Rater", facet_b = "Criterion", max_iter = 2)
t11 <- bias_count_table(bias)
t11_facets <- bias_count_table(bias, branch = "facets", fit = fit)
summary(t11)
p <- plot(t11, draw = FALSE)
p2 <- plot(t11, type = "lowcount_by_facet", draw = FALSE)
if (interactive()) {
  plot(
    t11,
    type = "cell_counts",
    draw = TRUE,
    main = "Bias Cell Counts (Customized)",
    palette = c(count = "#2b8cbe", low = "#cb181d"),
    label_angle = 45
  )
}

Build a bias-interaction plot-data bundle (preferred alias)

Description

Build a bias-interaction plot-data bundle (preferred alias)

Usage

bias_interaction_report(
  x,
  diagnostics = NULL,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001,
  top_n = 50,
  abs_t_warn = 2,
  abs_bias_warn = 0.5,
  p_max = 0.05,
  sort_by = c("abs_t", "abs_bias", "prob")
)

Arguments

Details

Preferred bundle API for interaction-bias diagnostics. The function can:

• use a precomputed bias object from estimate_bias(), or

• estimate internally from mfrm_fit + facet specification.

Value

A named list with bias-interaction plotting/report components. Class: mfrm_bias_interaction.

Interpreting output

Focus on ranked rows where multiple screening criteria converge:

• large absolute t statistic

• large absolute bias size

• small screening tail area

The bundle is optimized for downstream summary() and plot_bias_interaction() views.

Typical workflow

1. Run estimate_bias() (or provide mfrm_fit here).

2. Build bias_interaction_report(...).

3. Review summary(out) and visualize with plot_bias_interaction().

See Also

estimate_bias(), build_fixed_reports(), plot_bias_interaction()

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bias <- estimate_bias(fit, diag, facet_a = "Rater", facet_b = "Criterion", max_iter = 2)
out <- bias_interaction_report(bias, top_n = 10)
summary(out)
p_bi <- plot(out, draw = FALSE)
class(p_bi)

Build a bias-iteration report

Description

Build a bias-iteration report

Usage

bias_iteration_report(
  x,
  diagnostics = NULL,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001,
  top_n = 10
)

Arguments

Details

This report focuses on the recalibration path used by estimate_bias(). It provides a package-native counterpart to legacy iteration printouts by exposing the iteration table, convergence summary, and orientation audit in one bundle.

Value

A named list with:

• table: iteration history

• summary: one-row convergence summary

• orientation_audit: interaction-facet sign audit

• settings: resolved reporting options

See Also

estimate_bias(), bias_interaction_report(), build_fixed_reports()

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
out <- bias_iteration_report(fit, diagnostics = diag, facet_a = "Rater", facet_b = "Criterion")
summary(out)

Build a bias pairwise-contrast report

Description

Build a bias pairwise-contrast report

Usage

bias_pairwise_report(
  x,
  diagnostics = NULL,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001,
  target_facet = NULL,
  context_facet = NULL,
  top_n = 50,
  p_max = 0.05,
  sort_by = c("abs_t", "abs_contrast", "prob")
)

Arguments

Details

This helper exposes the pairwise contrast table that was previously only reachable through fixed-width output generation. It is available only for 2-way interactions. The pairwise contrast statistic uses a Welch/Satterthwaite approximation and is labeled as a Rasch-Welch comparison in the output metadata.

Value

A named list with:

• table: pairwise contrast rows

• summary: one-row contrast summary

• orientation_audit: interaction-facet sign audit

• settings: resolved reporting options

See Also

estimate_bias(), bias_interaction_report(), build_fixed_reports()

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
out <- bias_pairwise_report(fit, diagnostics = diag, facet_a = "Rater", facet_b = "Criterion")
summary(out)

Build APA text outputs from model results

Description

Build APA text outputs from model results

Usage

build_apa_outputs(
  fit,
  diagnostics,
  bias_results = NULL,
  context = list(),
  whexact = FALSE
)

Arguments

Details

context is an optional named list for narrative customization. Frequently used fields include:

• assessment, setting, scale_desc

• rater_training, raters_per_response

• rater_facet (used for targeted reliability note text)

• line_width (optional text wrapping width for report_text; default = 92)

Output text includes residual-PCA screening commentary if PCA diagnostics are available in diagnostics.

By default, report_text includes:

• model/data design summary (N, facet counts, scale range)

• optimization/convergence metrics (Converged, Iterations, LogLik, AIC, BIC)

• anchor/constraint summary (noncenter_facet, anchored levels, group anchors, dummy facets)

• category/threshold diagnostics (including disordered-step details when present)

• overall fit, misfit count, and top misfit levels

• facet reliability/separation, residual PCA summary, and bias-screen counts

Value

An object of class mfrm_apa_outputs with:

• report_text: APA-style Method/Results draft prose

• table_figure_notes: consolidated draft notes for tables/visuals

• table_figure_captions: draft caption candidates without figure numbering

• section_map: package-native section table for manuscript assembly

• contract: structured APA reporting contract used for downstream checks

Interpreting output

• report_text: manuscript-draft narrative covering Method (model specification, estimation, convergence) and Results (global fit, facet separation/reliability, misfit triage, category diagnostics, residual-PCA screening, bias screening). Written in third-person past tense following APA 7th edition conventions, but still intended for human review.

• table_figure_notes: reusable draft note blocks for table/figure appendices.

• table_figure_captions: draft caption candidates aligned to generated outputs.

When bias results or PCA diagnostics are not supplied, those sections are omitted from the narrative rather than producing placeholder text.

Typical workflow

1. Build diagnostics (and optional bias results).

2. Run build_apa_outputs(...).

3. Check summary(apa) for completeness.

4. Insert apa$report_text and note/caption fields into manuscript drafts after checking the listed cautions.

Context template

A minimal context list can include fields such as:

• assessment: name of the assessment task

• setting: administration context

• scale_desc: short description of the score scale

• rater_facet: rater facet label used in narrative reliability text

See Also

build_visual_summaries(), estimate_bias(), reporting_checklist(), mfrmr_reporting_and_apa

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "both")
apa <- build_apa_outputs(
  fit,
  diag,
  context = list(
    assessment = "Toy writing task",
    setting = "Demonstration dataset",
    scale_desc = "0-2 rating scale",
    rater_facet = "Rater"
  )
)
names(apa)
class(apa)
s_apa <- summary(apa)
s_apa$overview
chk <- reporting_checklist(fit, diagnostics = diag)
head(chk$checklist[, c("Section", "Item", "DraftReady", "NextAction")])
cat(apa$report_text)
apa$section_map[, c("SectionId", "Available")]

Build a screened linking chain across ordered calibrations

Description

Links a series of calibration waves by computing mean offsets between adjacent pairs of fits. Common linking elements (e.g., raters or items that appear in consecutive administrations) are used to estimate the scale shift. Cumulative offsets place all waves on a common metric anchored to the first wave. The procedure is intended as a practical screened linking aid, not as a full general-purpose equating framework.

Usage

build_equating_chain(
  fits,
  anchor_facets = NULL,
  include_person = FALSE,
  drift_threshold = 0.5
)

## S3 method for class 'mfrm_equating_chain'
print(x, ...)

## S3 method for class 'mfrm_equating_chain'
summary(object, ...)

## S3 method for class 'summary.mfrm_equating_chain'
print(x, ...)

Arguments

Details

The screened linking chain uses a screened link-offset method. For each pair of adjacent waves (A, B), the function:

1. Identifies common linking elements (facet levels present in both fits).

2. Computes per-element differences:

   d_e = \hat{\delta}_{e,B} - \hat{\delta}_{e,A}

3. Computes a preliminary link offset using the inverse-variance weighted mean of these differences when standard errors are available (otherwise an unweighted mean).

4. Screens out elements whose residual from that preliminary offset exceeds drift_threshold, then recomputes the final offset on the retained set.

5. Records Offset_SD (standard deviation of retained residuals) and Max_Residual (maximum absolute deviation from the mean) as indicators of link quality.

6. Flags links with fewer than 5 retained common elements in any linking facet as having thin support.

Cumulative offsets are computed by chaining link offsets from Wave 1 forward, placing all waves onto the metric of the first wave.

Elements whose per-link residual exceeds drift_threshold are flagged in ⁠$element_detail$Flag⁠. A high Offset_SD, many flagged elements, or a thin retained anchor set signals an unstable link that may compromise the resulting scale placement.

Value

Object of class mfrm_equating_chain with components:

links

Tibble of link-level statistics (offset, SD, etc.).

cumulative

Tibble of cumulative offsets per wave.

element_detail

Tibble of element-level linking details.

common_by_facet

Tibble of retained common-element counts by facet.

config

List of analysis configuration.

Which function should I use?

• Use anchor_to_baseline() for a single new wave anchored to a known baseline.

• Use detect_anchor_drift() when you want direct comparison against one reference wave.

• Use build_equating_chain() when no single wave should dominate and you want ordered, adjacent links across the series.

Interpreting output

• ⁠$links⁠: one row per adjacent pair with From, To, N_Common, N_Retained, Offset_Prelim, Offset, Offset_SD, and Max_Residual. Small Offset_SD relative to the offset indicates a consistent shift across elements. LinkSupportAdequate = FALSE means at least one linking facet retained fewer than 5 common elements after screening.

• ⁠$cumulative⁠: one row per wave with its cumulative offset from Wave 1. Wave 1 always has offset 0.

• ⁠$element_detail⁠: per-element linking statistics (estimate in each wave, difference, residual from mean offset, and flag status). Flagged elements may indicate DIF or rater re-training effects.

• ⁠$common_by_facet⁠: retained common-element counts by linking facet for each adjacent link.

• ⁠$config⁠: records wave names and analysis parameters.

• Read links before cumulative: weak adjacent links can make later cumulative offsets less trustworthy.

Typical workflow

1. Fit each administration wave separately: fit_a <- fit_mfrm(...).

2. Combine into an ordered named list: fits <- list(Spring23 = fit_s, Fall23 = fit_f, Spring24 = fit_s2).

3. Call chain <- build_equating_chain(fits).

4. Review summary(chain) for link quality.

5. Visualize with plot_anchor_drift(chain, type = "chain").

6. For problematic links, investigate flagged elements in chain$element_detail and consider removing them from the anchor set.

See Also

detect_anchor_drift(), anchor_to_baseline(), make_anchor_table(), plot_anchor_drift()

Examples

toy <- load_mfrmr_data("example_core")
people <- unique(toy$Person)
d1 <- toy[toy$Person %in% people[1:12], , drop = FALSE]
d2 <- toy[toy$Person %in% people[13:24], , drop = FALSE]
fit1 <- fit_mfrm(d1, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 10)
fit2 <- fit_mfrm(d2, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 10)
chain <- build_equating_chain(list(Form1 = fit1, Form2 = fit2))
summary(chain)
chain$cumulative

Build legacy-compatible fixed-width text reports

Description

Build legacy-compatible fixed-width text reports

Usage

build_fixed_reports(
  bias_results,
  target_facet = NULL,
  branch = c("facets", "original")
)

Arguments

Details

This function generates plain-text, fixed-width output intended to be read in console/log environments or exported into text reports.

The pairwise section (Table 14 style) is only generated for 2-way bias runs. For higher-order interactions (interaction_facets length >= 3), the function returns the bias table text and a note explaining why pairwise contrasts were skipped.

Value

A named list with:

• bias_fixed: fixed-width interaction table text

• pairwise_fixed: fixed-width pairwise contrast text

• pairwise_table: underlying pairwise data.frame

Interpreting output

• bias_fixed: fixed-width table of interaction effects.

• pairwise_fixed: pairwise contrast text (2-way only).

• pairwise_table: machine-readable contrast table.

• interaction_label: facets used for the bias run.

Typical workflow

1. Run estimate_bias().

2. Build text bundle with build_fixed_reports(...).

3. Use summary()/plot() for quick checks, then export text blocks.

Preferred route for new analyses

For new reporting workflows, prefer bias_interaction_report() and build_apa_outputs(). Use build_fixed_reports() when a fixed-width text artifact is specifically required for a compatibility handoff.

See Also

estimate_bias(), build_apa_outputs(), bias_interaction_report(), mfrmr_reports_and_tables, mfrmr_compatibility_layer

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bias <- estimate_bias(fit, diag, facet_a = "Rater", facet_b = "Criterion", max_iter = 2)
fixed <- build_fixed_reports(bias)
fixed_original <- build_fixed_reports(bias, branch = "original")
summary(fixed)
p <- plot(fixed, draw = FALSE)
p2 <- plot(fixed, type = "pvalue", draw = FALSE)
if (interactive()) {
  plot(
    fixed,
    type = "contrast",
    draw = TRUE,
    main = "Pairwise Contrasts (Customized)",
    palette = c(pos = "#1b9e77", neg = "#d95f02"),
    label_angle = 45
  )
}

Build a reproducibility manifest for an MFRM analysis

Description

Build a reproducibility manifest for an MFRM analysis

Usage

build_mfrm_manifest(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  population_prediction = NULL,
  unit_prediction = NULL,
  plausible_values = NULL,
  include_person_anchors = FALSE
)

Arguments

Details

This helper captures the package-native equivalent of the Streamlit app's configuration export. It summarizes analysis settings, source columns, anchoring information, and which downstream outputs are currently available.

Value

A named list with class mfrm_manifest.

When to use this

Use build_mfrm_manifest() when you want a compact, machine-readable record of how an analysis was run. Compared with related helpers:

• export_mfrm() writes analysis tables only.

• build_mfrm_manifest() records settings and available outputs.

• build_mfrm_replay_script() creates an executable R script.

• export_mfrm_bundle() writes a shareable folder of files.

Output

The returned bundle has class mfrm_manifest and includes:

• summary: one-row analysis overview

• environment: package/R/platform metadata

• model_settings: key-value model settings table

• source_columns: key-value data-column table

• estimation_control: key-value optimizer settings table

• anchor_summary: facet-level anchor summary

• anchors: machine-readable anchor table

• available_outputs: availability table for diagnostics/bias/PCA/prediction outputs

• settings: manifest build settings

Interpreting output

The summary table is the quickest place to confirm that you are looking at the intended analysis. The model_settings, source_columns, and estimation_control tables are designed for audit trails and method write-up. The available_outputs table is especially useful before building bundles, because it tells you whether residual PCA, anchors, bias results, or prediction-side artifacts are already available. A practical reading order is summary first, available_outputs second, and anchors last when reproducibility depends on fixed constraints.

Typical workflow

1. Fit a model with fit_mfrm() or run_mfrm_facets().

2. Compute diagnostics once with diagnose_mfrm() if you want explicit control over residual PCA.

3. Build a manifest and inspect summary plus available_outputs.

4. If you need files on disk, pass the same objects to export_mfrm_bundle().

See Also

export_mfrm_bundle(), build_mfrm_replay_script(), make_anchor_table(), reporting_checklist()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
manifest <- build_mfrm_manifest(fit, diagnostics = diag)
manifest$summary[, c("Model", "Method", "Observations", "Facets")]
manifest$available_outputs[, c("Component", "Available")]

Build a package-native replay script for an MFRM analysis

Description

Build a package-native replay script for an MFRM analysis

Usage

build_mfrm_replay_script(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  population_prediction = NULL,
  unit_prediction = NULL,
  plausible_values = NULL,
  data_file = "your_data.csv",
  script_mode = c("auto", "fit", "facets"),
  include_bundle = FALSE,
  bundle_dir = "analysis_bundle",
  bundle_prefix = "mfrmr_replay"
)

Arguments

Details

This helper mirrors the Streamlit app's reproducible-download idea, but uses mfrmr's installed API rather than embedding a separate estimation engine. The generated script assumes the user has the package installed and provides a data file at data_file.

Anchor and group-anchor constraints are embedded directly from the fitted object's stored configuration, so the script can replay anchored analyses without manual table reconstruction.

Value

A named list with class mfrm_replay_script.

When to use this

Use build_mfrm_replay_script() when you want a package-native recipe that another analyst can rerun later. Compared with related helpers:

• build_mfrm_manifest() records settings but does not run anything.

• build_mfrm_replay_script() produces executable R code.

• export_mfrm_bundle() can optionally write the replay script to disk.

Interpreting output

The returned object contains:

• summary: a one-row overview of the chosen replay mode and whether bundle export was included

• script: the generated R code as a single string

• anchors and group_anchors: the exact stored constraints that were embedded into the script

If ScriptMode is "facets", the script replays the higher-level run_mfrm_facets() workflow. If it is "fit", the script uses fit_mfrm() directly.

Mode guide

• "auto" is the safest default and follows the structure of the supplied object.

• "fit" is useful when you want a minimal script centered on fit_mfrm().

• "facets" is useful when you want to preserve the higher-level run_mfrm_facets() workflow, including stored column mapping.

Typical workflow

1. Finalize a fit and diagnostics object.

2. Generate the replay script with the path you want users to read from.

3. Write replay$script to disk, or let export_mfrm_bundle() do it for you.

4. Rerun the script in a fresh R session to confirm reproducibility.

See Also

build_mfrm_manifest(), export_mfrm_bundle(), run_mfrm_facets()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 25)
replay <- build_mfrm_replay_script(fit, data_file = "your_data.csv")
replay$summary[, c("ScriptMode", "ResidualPCA", "BiasPairs")]
cat(substr(replay$script, 1, 120))

Build an explicit simulation specification for MFRM design studies

Description

Build an explicit simulation specification for MFRM design studies

Usage

build_mfrm_sim_spec(
  n_person = 50,
  n_rater = 4,
  n_criterion = 4,
  raters_per_person = n_rater,
  score_levels = 4,
  theta_sd = 1,
  rater_sd = 0.35,
  criterion_sd = 0.25,
  noise_sd = 0,
  step_span = 1.4,
  thresholds = NULL,
  model = c("RSM", "PCM"),
  step_facet = "Criterion",
  assignment = c("crossed", "rotating", "resampled", "skeleton"),
  latent_distribution = c("normal", "empirical"),
  empirical_person = NULL,
  empirical_rater = NULL,
  empirical_criterion = NULL,
  assignment_profiles = NULL,
  design_skeleton = NULL,
  group_levels = NULL,
  dif_effects = NULL,
  interaction_effects = NULL
)

Arguments

Details

build_mfrm_sim_spec() creates an explicit, portable simulation specification that can be passed to simulate_mfrm_data(). The goal is to make the data-generating mechanism inspectable and reusable rather than relying only on ad hoc scalar arguments.

The resulting object records:

• design counts (n_person, n_rater, n_criterion, raters_per_person)

• latent spread assumptions (theta_sd, rater_sd, criterion_sd)

• optional empirical latent support values for semi-parametric simulation

• threshold structure (threshold_table)

• assignment design (assignment)

• optional empirical assignment profiles (assignment_profiles) with optional person-level Group labels

• optional observed response skeleton (design_skeleton) with optional person-level Group labels and observation-level Weight values

• optional signal tables for DIF and interaction bias

The current generator still targets the package's standard person x rater x criterion workflow. When threshold values are provided by StepFacet, the supported step facets are the generated Rater or Criterion levels.

Value

An object of class mfrm_sim_spec.

Interpreting output

This object does not contain simulated data. It is a data-generating specification that tells simulate_mfrm_data() how to generate them.

See Also

extract_mfrm_sim_spec(), simulate_mfrm_data()

Examples

spec <- build_mfrm_sim_spec(
  n_person = 30,
  n_rater = 4,
  n_criterion = 3,
  raters_per_person = 2,
  assignment = "rotating"
)
spec$model
spec$assignment
spec$threshold_table

Build warning and narrative summaries for visual outputs

Description

Build warning and narrative summaries for visual outputs

Usage

build_visual_summaries(
  fit,
  diagnostics,
  threshold_profile = "standard",
  thresholds = NULL,
  summary_options = NULL,
  whexact = FALSE,
  branch = c("original", "facets")
)

Arguments

Details

This function returns visual-keyed text maps to support dashboard/report rendering without hard-coding narrative strings in UI code.

thresholds can override any profile field by name. Common overrides:

• n_obs_min, n_person_min

• misfit_ratio_warn, zstd2_ratio_warn, zstd3_ratio_warn

• pca_first_eigen_warn, pca_first_prop_warn

summary_options supports:

• detail: "standard" or "detailed"

• max_facet_ranges: max facet-range snippets shown in visual summaries

• top_misfit_n: number of top misfit entries included

Value

An object of class mfrm_visual_summaries with:

• warning_map: visual-level warning text vectors

• summary_map: visual-level descriptive text vectors

• warning_counts, summary_counts: message counts by visual key

• crosswalk: FACETS-reference mapping for main visual keys

• branch, style, threshold_profile: branch metadata

Interpreting output

• warning_map: rule-triggered warning text by visual key.

• summary_map: descriptive narrative text by visual key.

• warning_counts / summary_counts: message-count tables for QA checks.

Typical workflow

1. inspect defaults with mfrm_threshold_profiles()

2. choose threshold_profile (strict / standard / lenient)

3. optionally override selected fields via thresholds

4. pass result maps to report/dashboard rendering logic

See Also

mfrm_threshold_profiles(), build_apa_outputs()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "both")
vis <- build_visual_summaries(fit, diag, threshold_profile = "strict")
vis2 <- build_visual_summaries(
  fit,
  diag,
  threshold_profile = "standard",
  thresholds = c(misfit_ratio_warn = 0.20, pca_first_eigen_warn = 2.0),
  summary_options = list(detail = "detailed", top_misfit_n = 5)
)
vis_facets <- build_visual_summaries(fit, diag, branch = "facets")
vis_facets$branch
summary(vis)
p <- plot(vis, type = "comparison", draw = FALSE)
p2 <- plot(vis, type = "warning_counts", draw = FALSE)
if (interactive()) {
  plot(
    vis,
    type = "comparison",
    draw = TRUE,
    main = "Warning vs Summary Counts (Customized)",
    palette = c(warning = "#cb181d", summary = "#3182bd"),
    label_angle = 45
  )
}

Build a category curve export bundle (preferred alias)

Description

Build a category curve export bundle (preferred alias)

Usage

category_curves_report(
  fit,
  theta_range = c(-6, 6),
  theta_points = 241,
  digits = 4,
  include_fixed = FALSE,
  fixed_max_rows = 400
)

Arguments

Details

Preferred high-level API for category-probability curve exports. Returns tidy curve coordinates and summary metadata for quick plotting/report integration without calling low-level helpers directly.

Value

A named list with category-curve components. Class: mfrm_category_curves.

Interpreting output

Use this report to inspect:

• where each category has highest probability across theta

• whether adjacent categories cross in expected order

• whether probability bands look compressed (often sparse categories)

Recommended read order:

1. summary(out) for compact diagnostics.

2. out$curve_points (or equivalent curve table) for downstream graphics.

3. plot(out) for a default visual check.

Typical workflow

1. Fit model with fit_mfrm().

2. Run category_curves_report() with suitable theta_points.

3. Use summary() and plot(); export tables for manuscripts/dashboard use.

See Also

category_structure_report(), rating_scale_table(), plot.mfrm_fit(), mfrmr_reports_and_tables, mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
out <- category_curves_report(fit, theta_points = 101)
summary(out)
names(out)
p_cc <- plot(out, draw = FALSE)
class(p_cc)

Build a category structure report (preferred alias)

Description

Build a category structure report (preferred alias)

Usage

category_structure_report(
  fit,
  diagnostics = NULL,
  theta_range = c(-6, 6),
  theta_points = 241,
  drop_unused = FALSE,
  include_fixed = FALSE,
  fixed_max_rows = 200
)

Arguments

Details

Preferred high-level API for category-structure diagnostics. This wraps the legacy-compatible bar/transition export and returns a stable bundle interface for reporting and plotting.

Value

A named list with category-structure components. Class: mfrm_category_structure.

Interpreting output

Key components include:

• category usage/fit table (count, expected, infit/outfit, ZSTD)

• threshold ordering and adjacent threshold gaps

• category transition-point table on the requested theta grid

Practical read order:

1. summary(out) for compact warnings and threshold ordering.

2. out$category_table for sparse/misfitting categories.

3. out$transition_points to inspect crossing structure.

4. plot(out) for quick visual check.

Typical workflow

1. fit_mfrm() -> model.

2. diagnose_mfrm() -> residual/fit diagnostics (optional argument here).

3. category_structure_report() -> category health snapshot.

4. summary() and plot() for draft-oriented review of category structure.

See Also

rating_scale_table(), category_curves_report(), plot.mfrm_fit(), mfrmr_reports_and_tables, mfrmr_visual_diagnostics

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
out <- category_structure_report(fit)
summary(out)
names(out)
p_cs <- plot(out, draw = FALSE)
class(p_cs)

Compare two or more fitted MFRM models

Description

Produce a side-by-side comparison of multiple fit_mfrm() results using information criteria, log-likelihood, and parameter counts. When exactly two nested models are supplied, a likelihood-ratio test is included.

Usage

compare_mfrm(..., labels = NULL, warn_constraints = TRUE, nested = FALSE)

Arguments

Details

Models should be fit to the same data (same rows, same person/facet columns) for the comparison to be meaningful. The function checks that observation counts match and warns otherwise.

Information-criterion ranking is reported only when all candidate models use the package's MML estimation path, analyze the same observations, and converge successfully. Raw AIC and BIC values are still shown for each model, but ⁠Delta_*⁠, weights, and preferred-model summaries are suppressed when the likelihood basis is not comparable enough for primary reporting.

Nesting: Two models are nested when one is a special case of the other obtained by imposing equality constraints. The most common nesting in MFRM is RSM (shared thresholds) inside PCM (item-specific thresholds). Models that differ only in estimation method (MML vs JML) on the same specification are not nested in the usual sense—use information criteria rather than LRT for that comparison.

The likelihood-ratio test (LRT) is reported only when exactly two models are supplied, nested = TRUE, the structural audit passes, and the difference in the number of parameters is positive:

\Lambda = -2 (\ell_{\mathrm{restricted}} - \ell_{\mathrm{full}}) \sim \chi^2_{\Delta p}

The LRT is asymptotically valid when models are nested and the data are independent. With small samples or boundary conditions (e.g., variance components near zero), treat p-values as approximate.

Value

An object of class mfrm_comparison (named list) with:

• table: data.frame of model-level statistics (LogLik, AIC, BIC, Delta_AIC, AkaikeWeight, Delta_BIC, BICWeight, npar, nobs, Model, Method, Converged, ICComparable).

• lrt: data.frame with likelihood-ratio test result (only when two models are supplied and nested = TRUE). Contains ChiSq, df, p_value.

• evidence_ratios: data.frame of pairwise Akaike-weight ratios (Model1, Model2, EvidenceRatio). NULL when weights cannot be computed.

• preferred: named list with the preferred model label by each criterion.

• comparison_basis: list describing whether IC and LRT comparisons were considered comparable. Includes a conservative nesting_audit.

Information-criterion diagnostics

In addition to raw AIC and BIC values, the function computes:

• Delta_AIC / Delta_BIC: difference from the best (minimum) value. A Delta < 2 is typically considered negligible; 4–7 suggests moderate evidence; > 10 indicates strong evidence against the higher-scoring model (Burnham & Anderson, 2002).

• AkaikeWeight / BICWeight: model probabilities derived from exp(-0.5 * Delta), normalised across the candidate set. An Akaike weight of 0.90 means the model has a 90\ being the best in the candidate set.

• Evidence ratios: pairwise ratios of Akaike weights, quantifying the relative evidence for one model over another (e.g., an evidence ratio of 5 means the preferred model is 5 times more likely).

AIC penalises complexity less than BIC; when they disagree, AIC favours the more complex model and BIC the simpler one.

What this comparison means

compare_mfrm() is a same-basis model-comparison helper. Its strongest claims apply only when the models were fit to the same response data, under a compatible likelihood basis, and with compatible constraint structure.

What this comparison does not justify

• Do not treat AIC/BIC differences as primary evidence when table$ICComparable is FALSE.

• Do not interpret the LRT unless nested = TRUE and the structural audit in comparison_basis$nesting_audit passes.

• Do not compare models fit to different datasets, different score codings, or materially different constraint systems as if they were commensurate.

Interpreting output

• Lower AIC/BIC values indicate better parsimony-accuracy trade-off only when table$ICComparable is TRUE.

• A significant LRT p-value suggests the more complex model provides a meaningfully better fit only when the nesting assumption truly holds.

• preferred indicates the model preferred by each criterion.

• evidence_ratios gives pairwise Akaike-weight ratios (returned only when Akaike weights can be computed for at least two models).

• When comparing more than two models, interpret evidence ratios cautiously—they do not adjust for multiple comparisons.

How to read the main outputs

• table: first-pass comparison table; start with ICComparable, Model, Method, AIC, and BIC.

• comparison_basis: records whether IC and LRT claims are defensible for the supplied models.

• lrt: nested-model test summary, present only when the requested and audited conditions are met.

• preferred: candidate preferred by each criterion when those summaries are available.

Recommended next step

Inspect comparison_basis before writing conclusions. If comparability is weak, treat the result as descriptive and revise the model setup (for example, explicit step_facet, common data, or common constraints) before using IC or LRT results in reporting.

Typical workflow

1. Fit two models with fit_mfrm() (e.g., RSM and PCM).

2. Compare with compare_mfrm(fit_rsm, fit_pcm).

3. Inspect summary(comparison) for AIC/BIC diagnostics and, when appropriate, an LRT.

See Also

fit_mfrm(), diagnose_mfrm()

Examples

toy <- load_mfrmr_data("example_core")

fit_rsm <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                     method = "MML", model = "RSM", maxit = 25)
fit_pcm <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                     method = "MML", model = "PCM",
                     step_facet = "Criterion", maxit = 25)
comp <- compare_mfrm(fit_rsm, fit_pcm, labels = c("RSM", "PCM"))
comp$table
comp$evidence_ratios

Compute design-weighted precision curves for RSM fits

Description

Calculates design-weighted score-variance curves across the latent trait (theta) for a fitted RSM many-facet Rasch model. Returns both an overall precision curve (⁠$tif⁠) and per-facet-level contribution curves (⁠$iif⁠) based on the realized observation pattern.

Usage

compute_information(fit, theta_range = c(-6, 6), theta_points = 201L)

Arguments

Details

For a polytomous Rasch model with K+1 categories, the score variance at theta for one observed design cell is:

I(\theta) = \sum_{k=0}^{K} P_k(\theta) \left(k - E(\theta)\right)^2

where P_k is the category probability and E(\theta) is the expected score at theta. In mfrmr, these cell-level variances are then aggregated with weights taken from the realized observation counts in 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 SE(\theta) = 1 / \sqrt{I(\theta)} for positive information values.

Value

An object of class mfrm_information (named list) with:

• tif: tibble with columns Theta, Information, SE. The Information column stores the design-weighted precision value.

• iif: tibble with columns Theta, Facet, Level, Information, and Exposure. Here too, Information stores a design-weighted contribution value retained under that column name for compatibility.

• theta_range: the evaluated theta range.

What tif and iif mean here

In mfrmr, this helper currently supports only RSM fits. The total curve (⁠$tif⁠) is the sum of design-weighted cell contributions across all non-person facet levels in the fitted model. The facet-level contribution curves (⁠$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.

What this quantity does not justify

• It is not a textbook many-facet test-information function for an abstract fixed item set.

• It should not be used as if it were design-free evidence about a form's precision independent of the realized observation pattern.

• It does not currently extend to PCM fits; the helper stops for model = "PCM".

When to use this

Use compute_information() when you want a design-weighted precision screen for an RSM fit along the latent continuum. In practice:

• start with the total precision curve for overall targeting across the realized observation pattern

• 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

• widen theta_range if you expect extreme measures and want to inspect the tails explicitly

Choosing the theta grid

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

Interpreting output

• ⁠$tif⁠: design-weighted precision curve data with theta, Information, and SE.

• ⁠$iif⁠: design-weighted facet-level contribution curves for an RSM fit.

• Higher information implies more precise measurement at that theta.

• SE is inversely related to information.

• Peaks in the total curve show the trait region where the realized calibration is most informative.

• Facet-level curves help explain which observed facet levels contribute to those peaks; they are not standalone item-information curves and should be read as design contributions.

How to read the main columns

• Theta: point on the latent continuum where the curve is evaluated.

• Information: design-weighted precision value at that theta.

• SE: approximate 1 / sqrt(Information) summary for positive values.

• Exposure: total realized observation weight contributing to a facet-level curve in ⁠$iif⁠.

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 precision_audit_report().

Typical workflow

1. Fit a model with fit_mfrm().

2. Run compute_information(fit).

3. Plot with plot_information(info, type = "tif").

4. If needed, inspect facet contributions with plot_information(info, type = "iif", facet = "Rater").

See Also

fit_mfrm(), plot_information()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 25)
info <- compute_information(fit)
head(info$tif)
info$tif$Theta[which.max(info$tif$Information)]

Build a data quality summary report (preferred alias)

Description

Build a data quality summary report (preferred alias)

Usage

data_quality_report(
  fit,
  data = NULL,
  person = NULL,
  facets = NULL,
  score = NULL,
  weight = NULL,
  include_fixed = FALSE
)

Arguments

Details

summary(out) is supported through summary(). plot(out) is dispatched through plot() for class mfrm_data_quality (type = "row_audit", "category_counts", "missing_rows").

Value

A named list with data-quality report components. Class: mfrm_data_quality.

Interpreting output

• summary: retained/dropped row overview.

• row_audit: reason-level breakdown for data issues.

• category_counts: post-filter category usage.

• unknown_elements: facet levels in raw data but not in fitted design.

Typical workflow

1. Run data_quality_report(...) with raw data.

2. Check row-audit and missing/unknown element sections.

3. Resolve issues before final estimation/reporting.

See Also

fit_mfrm(), describe_mfrm_data(), specifications_report(), mfrmr_reports_and_tables, mfrmr_compatibility_layer

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
out <- data_quality_report(
  fit, data = toy, person = "Person",
  facets = c("Rater", "Criterion"), score = "Score"
)
summary(out)
p_dq <- plot(out, draw = FALSE)
class(p_dq)

Summarize MFRM input data (TAM-style descriptive snapshot)

Description

Summarize MFRM input data (TAM-style descriptive snapshot)

Usage

describe_mfrm_data(
  data,
  person,
  facets,
  score,
  weight = NULL,
  rating_min = NULL,
  rating_max = NULL,
  keep_original = FALSE,
  include_person_facet = FALSE,
  include_agreement = TRUE,
  rater_facet = NULL,
  context_facets = NULL,
  agreement_top_n = NULL
)

Arguments

Details

This function provides a compact descriptive bundle similar to the pre-fit summaries commonly checked in TAM workflows: sample size, score distribution, per-facet coverage, and linkage counts. psych::describe() is used for numeric descriptives of score and weight.

Key data-quality checks to perform before fitting:

• Sparse categories: any score category with fewer than 10 weighted observations may produce unstable threshold estimates (Linacre, 2002). Consider collapsing adjacent categories.

• Unlinked elements: if a facet level has zero overlap with one or more levels of another facet, the design is disconnected and parameters cannot be placed on a common scale. Check linkage_summary for low connectivity.

• Extreme scores: persons or facet levels with all-minimum or all-maximum scores yield infinite logit estimates under JML; they are handled via Bayesian shrinkage under MML.

Value

A list of class mfrm_data_description with:

• overview: one-row run-level summary

• missing_by_column: missing counts in selected input columns

• score_descriptives: output from psych::describe() for score

• weight_descriptives: output from psych::describe() for weight

• score_distribution: weighted and raw score frequencies

• facet_level_summary: per-level usage and score summaries

• linkage_summary: person-facet connectivity diagnostics

• agreement: observed-score inter-rater agreement bundle

Interpreting output

Recommended order:

• overview: confirms sample size, facet count, and category span. The MinWeightedN column shows the smallest weighted observation count across all facet levels; values below 30 may lead to unstable parameter estimates.

• missing_by_column: identifies immediate data-quality risks. Any non-zero count warrants investigation before fitting.

• score_distribution: checks sparse/unused score categories. Balanced usage across categories is ideal; heavily skewed distributions may compress the measurement range.

• facet_level_summary and linkage_summary: checks per-level support and person-facet connectivity. Low linkage ratios indicate sparse or disconnected design blocks.

• agreement: optional observed inter-rater consistency summary (exact agreement, correlation, mean differences per rater pair).

Typical workflow

1. Run describe_mfrm_data() on long-format input.

2. Review summary(ds) and plot(ds, ...).

3. Resolve missingness/sparsity issues before fit_mfrm().

See Also

fit_mfrm(), audit_mfrm_anchors()

Examples

toy <- load_mfrmr_data("example_core")
ds <- describe_mfrm_data(
  data = toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score"
)
s_ds <- summary(ds)
s_ds$overview
p_ds <- plot(ds, draw = FALSE)
class(p_ds)

Detect anchor drift across multiple calibrations

Description

Compares facet estimates across two or more calibration waves to identify elements whose difficulty/severity has shifted beyond acceptable thresholds. Useful for monitoring rater drift over time or checking the stability of item banks.

Usage

detect_anchor_drift(
  fits,
  facets = NULL,
  drift_threshold = 0.5,
  flag_se_ratio = 2,
  reference = 1L,
  include_person = FALSE
)

## S3 method for class 'mfrm_anchor_drift'
print(x, ...)

## S3 method for class 'mfrm_anchor_drift'
summary(object, ...)

## S3 method for class 'summary.mfrm_anchor_drift'
print(x, ...)

Arguments

Details

For each non-reference wave, the function extracts facet-level estimates using make_anchor_table() and computes the element-by-element difference against the reference wave. Standard errors are obtained from diagnose_mfrm() applied to each fit. Only elements common to both the reference and a comparison wave are included. Before reporting drift, the function removes the weighted common-element link offset between the two waves so that Drift represents residual instability rather than the overall shift between calibrations. The function also records how many common elements survive the screening step within each linking facet and treats fewer than 5 retained common elements per facet as thin support.

An element is flagged when either condition is met:

|\Delta_e| > \texttt{drift\_threshold}

|\Delta_e / SE_{\Delta_e}| > \texttt{flag\_se\_ratio}

The dual-criterion approach guards against flagging elements with large but imprecise estimates, and against missing small but precisely estimated shifts.

When facets is NULL, all non-Person facets are compared. Providing a subset (e.g., facets = "Criterion") restricts comparison to those facets only.

Value

Object of class mfrm_anchor_drift with components:

drift_table

Tibble of element-level drift statistics.

summary

Drift summary aggregated by facet and wave.

common_elements

Tibble of pairwise common-element counts.

common_by_facet

Tibble of retained common-element counts by facet.

config

List of analysis configuration.

Which function should I use?

• Use anchor_to_baseline() when your starting point is raw new data plus a single baseline fit.

• Use detect_anchor_drift() when you already have multiple fitted waves and want a reference-versus-wave comparison.

• Use build_equating_chain() when the waves form a sequence and you need cumulative linking offsets.

Interpreting output

• ⁠$drift_table⁠: one row per element x wave combination, with columns Facet, Level, Wave, Ref_Est, Wave_Est, LinkOffset, Drift, SE_Ref, SE_Wave, SE, Drift_SE_Ratio, LinkSupportAdequate, and Flag. Large drift signals instability after alignment to the common-element link.

• ⁠$summary⁠: aggregated statistics by facet and wave: number of elements, mean/max absolute drift, and count of flagged elements.

• ⁠$common_elements⁠: pairwise common-element counts in tidy table form. Small overlap weakens the comparison and results should be interpreted cautiously.

• ⁠$common_by_facet⁠: retained common-element counts by linking facet for each reference-vs-wave comparison. LinkSupportAdequate = FALSE means the link rests on fewer than 5 retained common elements in at least one facet.

• ⁠$config⁠: records the analysis parameters for reproducibility.

• A practical reading order is summary(drift) first, then drift$drift_table, then drift$common_by_facet if overlap looks thin.

Typical workflow

1. Fit separate models for each administration wave.

2. Combine into a named list: fits <- list(Spring = fit_s, Fall = fit_f).

3. Call drift <- detect_anchor_drift(fits).

4. Review summary(drift) and plot_anchor_drift(drift).

5. Flagged elements may need to be removed from anchor sets or investigated for substantive causes (e.g., rater re-training).

See Also

anchor_to_baseline(), build_equating_chain(), make_anchor_table(), plot_anchor_drift(), mfrmr_linking_and_dff

Examples

d1 <- load_mfrmr_data("study1")
d2 <- load_mfrmr_data("study2")
fit1 <- fit_mfrm(d1, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 15)
fit2 <- fit_mfrm(d2, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", maxit = 15)
drift <- detect_anchor_drift(list(Wave1 = fit1, Wave2 = fit2))
summary(drift)
head(drift$drift_table[, c("Facet", "Level", "Wave", "Drift", "Flag")])
drift$common_elements

Compute diagnostics for an mfrm_fit object

Description

Compute diagnostics for an mfrm_fit object

Usage

diagnose_mfrm(
  fit,
  interaction_pairs = NULL,
  top_n_interactions = 20,
  whexact = FALSE,
  residual_pca = c("none", "overall", "facet", "both"),
  pca_max_factors = 10L
)

Arguments

Details

This function computes a diagnostic bundle used by downstream reporting. It calculates element-level fit statistics, approximate facet separation/reliability summaries, residual-based QC diagnostics, and optionally residual PCA for exploratory residual-structure screening.

Key fit statistics computed for each element:

• Infit MnSq: information-weighted mean-square residual; sensitive to on-target misfitting patterns. Expected value = 1.0.

• Outfit MnSq: unweighted mean-square residual; sensitive to off-target outliers. Expected value = 1.0.

• ZSTD: Wilson-Hilferty cube-root transformation of MnSq to an approximate standard normal deviate.

• PTMEA: point-measure correlation (item-rest correlation in MFRM context); positive values confirm alignment with the latent trait.

Misfit flagging guidelines (Bond & Fox, 2015):

• MnSq < 0.5: overfit (too predictable; may inflate reliability)

• MnSq 0.5–1.5: productive for measurement

• MnSq > 1.5: underfit (noise degrades measurement)

• |\mathrm{ZSTD}| > 2: statistically significant misfit (5\

When Infit and Outfit disagree, Infit is generally more informative because it downweights extreme observations. Large Outfit with acceptable Infit typically indicates a few outlying responses rather than systematic misfit.

interaction_pairs controls which facet interactions are summarized. Each element can be:

• a length-2 character vector such as c("Rater", "Criterion"), or

• omitted (NULL) to let the function select top interactions automatically.

Residual PCA behavior:

• "none": skip PCA (fastest; recommended for initial exploration)

• "overall": compute overall residual PCA across all facets

• "facet": compute facet-specific residual PCA for each facet

• "both": compute both overall and facet-specific PCA

Overall PCA examines the person \times combined-facet residual matrix; facet-specific PCA examines person \times facet-level matrices. These summaries are exploratory screens for residual structure, not standalone proofs for or against unidimensionality. Facet-specific PCA can help localise where a stronger residual signal is concentrated.

Value

An object of class mfrm_diagnostics including:

• obs: observed/expected/residual-level table

• measures: facet/person fit table (Infit, Outfit, ZSTD, PTMEA)

• overall_fit: overall fit summary

• fit: element-level fit diagnostics

• reliability: facet-level model/real separation and reliability

• precision_profile: one-row summary of the active precision tier and its recommended use

• precision_audit: package-native checks for SE, CI, and reliability

• facet_precision: facet-level precision summary by distribution basis and SE mode

• facets_chisq: fixed/random facet variability summary

• interactions: top interaction diagnostics

• interrater: inter-rater agreement bundle (summary, pairs) including agreement and rater-severity spread indices

• unexpected: unexpected-response bundle

• fair_average: adjusted-score reference bundle

• displacement: displacement diagnostics bundle

• approximation_notes: method notes for SE/CI/reliability summaries

• residual_pca_overall: optional overall PCA object

• residual_pca_by_facet: optional facet PCA objects

Reading key components

Practical interpretation often starts with:

• overall_fit: global infit/outfit and degrees of freedom.

• reliability: facet-level model/real separation and reliability. MML uses model-based ModelSE values where available; JML keeps these quantities as exploratory approximations.

• fit: element-level misfit scan (Infit, Outfit, ZSTD).

• unexpected, fair_average, displacement: targeted QC bundles.

• approximation_notes: method notes for SE/CI/reliability summaries.

Interpreting output

Start with overall_fit and reliability, then move to element-level diagnostics (fit) and targeted bundles (unexpected, fair_average, displacement, interrater, facets_chisq).

Consistent signals across multiple components are typically more robust than a single isolated warning. For example, an element flagged for both high Outfit and high displacement is more concerning than one flagged on a single criterion.

SE is kept as a compatibility alias for ModelSE. RealSE is a fit-adjusted companion defined as ModelSE * sqrt(max(Infit, 1)). Reliability tables report model and fit-adjusted bounds from observed variance, error variance, and true variance; JML entries should still be treated as exploratory.

Typical workflow

1. Run diagnose_mfrm(fit, residual_pca = "none") for baseline diagnostics.

2. Inspect summary(diag) and targeted tables/plots.

3. If needed, rerun with residual PCA ("overall" or "both").

See Also

fit_mfrm(), analyze_residual_pca(), build_visual_summaries(), mfrmr_visual_diagnostics, mfrmr_reporting_and_apa

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
s_diag <- summary(diag)
s_diag$overview[, c("Observations", "Facets", "Categories")]
p_qc <- plot_qc_dashboard(fit, diagnostics = diag, draw = FALSE)
class(p_qc)

# Optional: include residual PCA in the diagnostic bundle
diag_pca <- diagnose_mfrm(fit, residual_pca = "overall")
pca <- analyze_residual_pca(diag_pca, mode = "overall")
head(pca$overall_table)

# Reporting route:
prec <- precision_audit_report(fit, diagnostics = diag)
summary(prec)

Compute interaction table between a facet and a grouping variable

Description

Produces a cell-level interaction table showing Obs-Exp differences, standardized residuals, and screening statistics for each facet-level x group-value cell.

Usage

dif_interaction_table(
  fit,
  diagnostics,
  facet,
  group,
  data = NULL,
  min_obs = 10,
  p_adjust = "holm",
  abs_t_warn = 2,
  abs_bias_warn = 0.5
)

Arguments

Details

This function uses the fitted model's observation-level residuals (from the internal compute_obs_table() function) rather than re-estimating the model. For each facet-level x group-value cell, it computes:

• N: number of observations in the cell

• ObsScore: sum of observed scores

• ExpScore: sum of expected scores

• ObsExpAvg: mean observed-minus-expected difference

• Var_sum: sum of model variances

• StdResidual: (ObsScore - ExpScore) / sqrt(Var_sum)

• t: approximate t-statistic (equal to StdResidual)

• df: N - 1

• p_value: two-tailed p-value from the t-distribution

Value

Object of class mfrm_dif_interaction with:

• table: tibble with per-cell statistics and flags.

• summary: tibble summarizing flagged and sparse cell counts.

• config: list of analysis parameters.

When to use this instead of analyze_dff()

Use dif_interaction_table() when you want cell-level screening for a single facet-by-group table. Use analyze_dff() when you want group-pair contrasts summarized into differential-functioning effect sizes and method-appropriate classifications.

Further guidance

For plot selection and follow-up diagnostics, see mfrmr_visual_diagnostics.

Interpreting output

• ⁠$table⁠: the full interaction table with one row per cell.

• ⁠$summary⁠: overview counts of flagged and sparse cells.

• ⁠$config⁠: analysis configuration parameters.

• Cells with ⁠|t| > abs_t_warn⁠ or ⁠|ObsExpAvg| > abs_bias_warn⁠ are flagged in the flag_t and flag_bias columns.

• Sparse cells (N < min_obs) have sparse = TRUE and NA statistics.

Typical workflow

1. Fit a model with fit_mfrm().

2. Run dif_interaction_table(fit, diag, facet = "Rater", group = "Gender", data = df).

3. Inspect ⁠$table⁠ for flagged cells.

4. Visualize with plot_dif_heatmap().

See Also

analyze_dff(), analyze_dif(), plot_dif_heatmap(), dif_report(), estimate_bias()

Examples

toy <- load_mfrmr_data("example_bias")

fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
int <- dif_interaction_table(fit, diag, facet = "Rater",
                             group = "Group", data = toy, min_obs = 2)
int$summary
head(int$table[, c("Level", "GroupValue", "ObsExpAvg", "flag_bias")])

Generate a differential-functioning interpretation report

Description

Produces APA-style narrative text interpreting the results of a differential- functioning analysis or interaction table. For method = "refit", the report summarises the number of facet levels classified as negligible (A), moderate (B), and large (C). For method = "residual", it summarises screening-positive results, lists the specific levels and their direction, and includes a caveat about the distinction between construct-relevant variation and measurement bias.

Usage

dif_report(dif_result, ...)

Arguments

Details

When dif_result is an mfrm_dff/mfrm_dif object, the report is based on the pairwise differential-functioning contrasts in ⁠$dif_table⁠. When it is an mfrm_dif_interaction object, the report uses the cell-level statistics and flags from ⁠$table⁠.

For method = "refit", ETS-style magnitude labels are used only when subgroup calibrations were successfully linked back to a common baseline scale; otherwise the report labels those contrasts as unclassified because the refit difference is descriptive rather than comparable on a linked logit scale. For method = "residual", the report describes screening-positive versus screening-negative contrasts instead of applying ETS labels.

Value

Object of class mfrm_dif_report with narrative, counts, large_dif, and config.

Interpreting output

• ⁠$narrative⁠: character scalar with the full narrative text.

• ⁠$counts⁠: named integer vector of method-appropriate counts.

• ⁠$large_dif⁠: tibble of large ETS results (method = "refit") or screening-positive contrasts/cells (method = "residual").

• ⁠$config⁠: analysis configuration inherited from the input.

Typical workflow

1. Run analyze_dff() / analyze_dif() or dif_interaction_table().

2. Pass the result to dif_report().

3. Print the report or extract ⁠$narrative⁠ for inclusion in a manuscript.

See Also

analyze_dff(), analyze_dif(), dif_interaction_table(), plot_dif_heatmap(), build_apa_outputs()

Examples

toy <- load_mfrmr_data("example_bias")

fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                 method = "JML", model = "RSM", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
dif <- analyze_dff(fit, diag, facet = "Rater", group = "Group", data = toy)
rpt <- dif_report(dif)
cat(rpt$narrative)

Compute displacement diagnostics for facet levels

Description

Compute displacement diagnostics for facet levels

Usage

displacement_table(
  fit,
  diagnostics = NULL,
  facets = NULL,
  anchored_only = FALSE,
  abs_displacement_warn = 0.5,
  abs_t_warn = 2,
  top_n = NULL
)

Arguments

Details

Displacement is computed as a one-step Newton update: sum(residual) / sum(information) for each facet level. This approximates how much a level would move if constraints were relaxed.

Value

A named list with:

• table: displacement diagnostics by level

• summary: one-row summary

• thresholds: applied thresholds

Interpreting output

• table: level-wise displacement and flag indicators.

• summary: count/share of flagged levels.

• thresholds: displacement and t-value cutoffs.

Large absolute displacement in anchored levels suggests potential instability in anchor assumptions.

Typical workflow

1. Run displacement_table(fit, anchored_only = TRUE) for anchor checks.

2. Inspect summary(disp) then detailed rows.

3. Visualize with plot_displacement().

Output columns

The table data.frame contains:

Facet, Level

Facet name and element label.

Displacement

One-step Newton displacement estimate (logits).

DisplacementSE

Standard error of the displacement.

DisplacementT

Displacement / SE ratio.

Estimate, SE

Current measure estimate and its standard error.

N

Number of observations involving this level.

AnchorValue, AnchorStatus, AnchorType

Anchor metadata.

Flag

Logical; TRUE when displacement exceeds thresholds.

See Also

diagnose_mfrm(), unexpected_response_table(), fair_average_table()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
disp <- displacement_table(fit, anchored_only = FALSE)
summary(disp)
p_disp <- plot(disp, draw = FALSE)
class(p_disp)

Simulated MFRM datasets based on Eckes and Jin (2021)

Description

Synthetic many-facet rating datasets in long format. All datasets include one row per observed rating.

Format

A data.frame with 5 columns:

Study

Study label ("Study1" or "Study2").

Person

Person/respondent identifier.

Rater

Rater identifier.

Criterion

Criterion facet label.

Score

Observed category score.

Details

Available data objects:

• mfrmr_example_core

• mfrmr_example_bias

• ej2021_study1

• ej2021_study2

• ej2021_combined

• ej2021_study1_itercal

• ej2021_study2_itercal

• ej2021_combined_itercal

Naming convention:

• study1 / study2: separate simulation studies

• combined: row-bind of study1 and study2

• ⁠_itercal⁠: iterative-calibration variant

Use load_mfrmr_data() for programmatic selection by key.

Data dimensions

Score range: 1–4 (four-category rating scale).

Simulation design

Person ability is drawn from N(0, 1). Rater severity effects span approximately -0.5 to +0.5 logits. Criterion difficulty effects span approximately -0.3 to +0.3 logits. Scores are generated from the resulting linear predictor plus Gaussian noise, then discretized into four categories. The ⁠_itercal⁠ variants use a second iteration of calibrated rater severity parameters.

Interpreting output

Each dataset is already in long format and can be passed directly to fit_mfrm() after confirming column-role mapping.

Typical workflow

1. Inspect available datasets with list_mfrmr_data().

2. Load one dataset using load_mfrmr_data().

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

Source

Simulated for this package with design settings informed by Eckes and Jin (2021).

Examples

data("ej2021_study1", package = "mfrmr")
head(ej2021_study1)
table(ej2021_study1$Study)

Estimate bias across multiple facet pairs

Description

Estimate bias across multiple facet pairs

Usage

estimate_all_bias(
  fit,
  diagnostics = NULL,
  pairs = NULL,
  include_person = FALSE,
  drop_empty = TRUE,
  keep_errors = TRUE,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001
)

Arguments

Details

This function orchestrates repeated calls to estimate_bias() across multiple facet pairs and returns a consolidated bundle.

Bias/interaction in MFRM refers to a systematic departure from the additive model for a specific combination of facet elements (e.g., a particular rater is unexpectedly harsh on a particular criterion). See estimate_bias() for the mathematical formulation.

When pairs = NULL, the function builds all 2-way combinations of modelled facets automatically. For a model with facets Rater, Criterion, and Task, this yields Rater\timesCriterion, Rater\timesTask, and Criterion\timesTask.

The summary table aggregates results across pairs:

• Rows: number of interaction cells estimated

• Significant: count of cells with |t| \ge 2

• MeanAbsBias: average absolute bias magnitude (logits)

Per-pair failures (e.g., insufficient data for a sparse pair) are captured in errors rather than stopping the entire batch.

Value

A named list with class mfrm_bias_collection.

Output

The returned object is a bundle-like list with class mfrm_bias_collection and components such as:

• summary: one row per requested interaction

• by_pair: named list of successful estimate_bias() outputs

• errors: per-pair error log

• settings: resolved execution settings

• primary: first successful bias bundle, useful for downstream helpers

Typical workflow

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

2. Run estimate_all_bias() to compute app-style multi-pair interactions.

3. Pass the resulting by_pair list into reporting_checklist() or facet_quality_dashboard().

See Also

estimate_bias(), reporting_checklist(), facet_quality_dashboard()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bias_all <- estimate_all_bias(fit, diagnostics = diag)
bias_all$summary[, c("Interaction", "Rows", "Significant")]

Estimate legacy-compatible bias/interaction terms iteratively

Description

Estimate legacy-compatible bias/interaction terms iteratively

Usage

estimate_bias(
  fit,
  diagnostics,
  facet_a = NULL,
  facet_b = NULL,
  interaction_facets = NULL,
  max_abs = 10,
  omit_extreme = TRUE,
  max_iter = 4,
  tol = 0.001
)

Arguments

Details

Bias (interaction) in MFRM refers to a systematic departure from the additive model: a specific rater-criterion (or higher-order) combination produces scores that are consistently higher or lower than predicted by the main effects alone. For example, Rater A might be unexpectedly harsh on Criterion 2 despite being lenient overall.

Mathematically, the bias term b_{jc} for rater j on criterion c modifies the linear predictor:

\eta_{njc} = \theta_n - \delta_j - \beta_c - b_{jc}

The function estimates b_{jc} from the residuals of the fitted (additive) model using iterative recalibration in a legacy-compatible style (Myford & Wolfe, 2003, 2004):

b_{jc} = \frac{\sum_n (X_{njc} - E_{njc})} {\sum_n \mathrm{Var}_{njc}}

Each iteration updates expected scores using the current bias estimates, then re-computes the bias. Convergence is reached when the maximum absolute change in bias estimates falls below tol.

• For two-way mode, use facet_a and facet_b (or interaction_facets with length 2).

• For higher-order mode, provide interaction_facets with length >= 3.

Value

An object of class mfrm_bias with:

• table: interaction rows with effect size, SE, screening t/p metadata, reporting-use flags, and fit columns

• summary: compact summary statistics

• chi_sq: fixed-effect chi-square style screening summary

• facet_a, facet_b: first two analyzed facet names (legacy compatibility)

• interaction_facets, interaction_order, interaction_mode: full interaction metadata

• iteration: iteration history/metadata

What this screening means

estimate_bias() summarizes interaction departures from the additive MFRM. It is best read as a targeted screening tool for potentially noteworthy cells or facet combinations that may merit substantive review.

What this screening does not justify

• t and Prob. are screening metrics, not formal inferential quantities.

• A flagged interaction cell is not, by itself, proof of rater bias or construct-irrelevant variance.

• Non-flagged cells should not be over-read as evidence that interaction effects are absent.

Interpreting output

Use summary for global magnitude, then inspect table for cell-level interaction effects.

Prioritize rows with:

• larger ⁠|Bias Size|⁠ (effect on logit scale; > 0.5 logits is typically noteworthy, > 1.0 is large)

• larger ⁠|t|⁠ among the screening metrics (|t| \ge 2 suggests a screen-positive interaction cell)

• smaller Prob. among the screening metrics

A positive ⁠Obs-Exp Average⁠ means the cell produced higher scores than the additive model predicts (unexpected leniency); negative means unexpected harshness.

iteration helps verify whether iterative recalibration stabilized. If the maximum change on the final iteration is still above tol, consider increasing max_iter.

Typical workflow

1. Fit and diagnose model.

2. Run estimate_bias(...) for target interaction facets.

3. Review summary(bias) and bias$table.

4. Visualize/report via plot_bias_interaction() and build_fixed_reports().

Interpreting key output columns

In bias$table, the most-used columns are:

• ⁠Bias Size⁠: estimated interaction effect b_{jc} (logit scale)

• t and Prob.: screening metrics, not formal inferential quantities

• ⁠Obs-Exp Average⁠: direction and practical size of observed-vs-expected gap on the raw-score metric

The chi_sq element provides a fixed-effect heterogeneity screen across all interaction cells.

Recommended next step

Use plot_bias_interaction() to inspect the flagged cells visually, then integrate the result with DFF, linking, or substantive scoring review before making formal claims about fairness or invariance.

See Also

build_fixed_reports(), build_apa_outputs()

Examples

toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bias <- estimate_bias(fit, diag, facet_a = "Rater", facet_b = "Criterion", max_iter = 2)
summary(bias)
p_bias <- plot_bias_interaction(bias, draw = FALSE)
class(p_bias)

Build an estimation-iteration report (preferred alias)

Description

Build an estimation-iteration report (preferred alias)

Usage

estimation_iteration_report(
  fit,
  max_iter = 20,
  reltol = NULL,
  include_prox = TRUE,
  include_fixed = FALSE
)

Arguments

Details

summary(out) is supported through summary(). plot(out) is dispatched through plot() for class mfrm_iteration_report (type = "residual", "logit_change", "objective").

Value

A named list with iteration-report components. Class: mfrm_iteration_report.

Interpreting output

• iterations: trajectory of convergence indicators by iteration.

• summary: final status and stopping diagnostics.

• optional PROX row: pseudo-initial reference point when enabled.

Typical workflow

1. Run estimation_iteration_report(fit).

2. Inspect plateau/stability patterns in summary/plot.

3. Adjust optimization settings if convergence looks weak.

See Also

fit_mfrm(), specifications_report(), data_quality_report(), mfrmr_reports_and_tables, mfrmr_compatibility_layer

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
out <- estimation_iteration_report(fit, max_iter = 5)
summary(out)
p_iter <- plot(out, draw = FALSE)
class(p_iter)

Evaluate MFRM design conditions by repeated simulation

Description

Evaluate MFRM design conditions by repeated simulation

Usage

evaluate_mfrm_design(
  n_person = c(30, 50, 100),
  n_rater = c(3, 5),
  n_criterion = c(3, 5),
  raters_per_person = n_rater,
  reps = 10,
  score_levels = 4,
  theta_sd = 1,
  rater_sd = 0.35,
  criterion_sd = 0.25,
  noise_sd = 0,
  step_span = 1.4,
  fit_method = c("JML", "MML"),
  model = c("RSM", "PCM"),
  step_facet = NULL,
  maxit = 25,
  quad_points = 7,
  residual_pca = c("none", "overall", "facet", "both"),
  sim_spec = NULL,
  seed = NULL
)

Arguments

Details

This helper runs a compact Monte Carlo design study for common rater-by-item many-facet settings.

For each design condition, the function:

1. generates synthetic data with simulate_mfrm_data()

2. fits the requested MFRM with fit_mfrm()

3. computes diagnostics with diagnose_mfrm()

4. stores recovery and precision summaries by facet

The result is intended for planning questions such as:

• how many raters are needed for stable rater separation?

• how does raters_per_person affect severity recovery?

• when do category counts become too sparse for comfortable interpretation?

This is a parametric simulation study. It does not take one observed design (for example, 4 raters x 30 persons x 3 criteria) and analytically extrapolate what would happen under a different design (for example, 2 raters x 40 persons x 5 criteria). Instead, you specify a design grid and data-generating assumptions (latent spread, facet spread, thresholds, noise, and scoring structure), and the function repeatedly generates synthetic data under those assumptions.

When you want the simulated conditions to resemble an existing study, use substantive knowledge or estimates from that study to choose theta_sd, rater_sd, criterion_sd, score_levels, and related settings before running the design evaluation.

When sim_spec is supplied, the function uses it as the explicit data-generating mechanism. This is the recommended route when you want a design study to stay close to a previously fitted run while still varying the candidate sample sizes or rater-assignment counts.

Recovery metrics are reported only when the generator and fitted model target the same facet-parameter contract. In practice this means the same model, and for PCM, the same step_facet. When these do not align, recovery fields are set to NA and the output records the reason.

Value

An object of class mfrm_design_evaluation with components:

• design_grid: evaluated design conditions

• results: facet-level replicate results

• rep_overview: run-level status and timing

• settings: simulation settings

• ademp: simulation-study metadata (aims, DGM, estimands, methods, performance measures)

Reported metrics

Facet-level simulation results include:

• Separation (G = \mathrm{SD_{adj}} / \mathrm{RMSE}): how many statistically distinct strata the facet resolves.

• Reliability (G^2 / (1 + G^2)): analogous to Cronbach's \alpha for the reproducibility of element ordering.

• Strata ((4G + 1) / 3): number of distinguishable groups.

• Mean Infit and Outfit: average fit mean-squares across elements.

• MisfitRate: share of elements with |\mathrm{ZSTD}| > 2.

• SeverityRMSE: root-mean-square error of recovered parameters vs the known truth after facet-wise mean alignment, so that the usual Rasch/MFRM location indeterminacy does not inflate recovery error. This quantity is reported only when the generator and fitted model target the same facet-parameter contract.

• SeverityBias: mean signed recovery error after the same alignment; values near zero are expected. This is likewise omitted when the generator/fitted-model contract does not align.

Interpreting output

Start with summary(x)$design_summary, then plot one focal metric at a time (for example rater Separation or criterion SeverityRMSE).

Higher separation/reliability is generally better, whereas lower SeverityRMSE, MeanMisfitRate, and MeanElapsedSec are preferable.

When choosing among designs, look for the point where increasing n_person or raters_per_person yields diminishing returns in separation and RMSE—this identifies the cost-effective design frontier. ConvergedRuns / reps should be near 1.0; low convergence rates indicate the design is too small for the chosen estimation method.

References

The simulation logic follows the general Monte Carlo / operating-characteristic framework described by Morris, White, and Crowther (2019) and the ADEMP-oriented planning/reporting guidance summarized for psychology by Siepe et al. (2024). In mfrmr, evaluate_mfrm_design() is a practical many-facet design-planning wrapper rather than a direct reproduction of one published simulation study.

• Morris, T. P., White, I. R., & Crowther, M. J. (2019). Using simulation studies to evaluate statistical methods. Statistics in Medicine, 38(11), 2074-2102.

• Siepe, B. S., Bartos, F., Morris, T. P., Boulesteix, A.-L., Heck, D. W., & Pawel, S. (2024). Simulation studies for methodological research in psychology: A standardized template for planning, preregistration, and reporting. Psychological Methods.

See Also

simulate_mfrm_data(), summary.mfrm_design_evaluation, plot.mfrm_design_evaluation

Examples

sim_eval <- evaluate_mfrm_design(
  n_person = c(30, 50),
  n_rater = 4,
  n_criterion = 4,
  raters_per_person = 2,
  reps = 1,
  maxit = 15,
  seed = 123
)
s_eval <- summary(sim_eval)
s_eval$design_summary[, c("Facet", "n_person", "MeanSeparation", "MeanSeverityRMSE")]
p_eval <- plot(sim_eval, facet = "Rater", metric = "separation", x_var = "n_person", draw = FALSE)
names(p_eval)

Evaluate DIF power and bias-screening behavior under known simulated signals

Description

Evaluate DIF power and bias-screening behavior under known simulated signals

Usage

evaluate_mfrm_signal_detection(
  n_person = c(30, 50, 100),
  n_rater = c(4),
  n_criterion = c(4),
  raters_per_person = n_rater,
  reps = 10,
  group_levels = c("A", "B"),
  reference_group = NULL,
  focal_group = NULL,
  dif_level = NULL,
  dif_effect = 0.6,
  bias_rater = NULL,
  bias_criterion = NULL,
  bias_effect = -0.8,
  score_levels = 4,
  theta_sd = 1,
  rater_sd = 0.35,
  criterion_sd = 0.25,
  noise_sd = 0,
  step_span = 1.4,
  fit_method = c("JML", "MML"),
  model = c("RSM", "PCM"),
  step_facet = NULL,
  maxit = 25,
  quad_points = 7,
  residual_pca = c("none", "overall", "facet", "both"),
  sim_spec = NULL,
  dif_method = c("residual", "refit"),
  dif_min_obs = 10,
  dif_p_adjust = "holm",
  dif_p_cut = 0.05,
  dif_abs_cut = 0.43,
  bias_max_iter = 2,
  bias_p_cut = 0.05,
  bias_abs_t = 2,
  seed = NULL
)

Arguments

Details

This function performs Monte Carlo design screening for two related tasks: DIF detection via analyze_dff() and interaction-bias screening via estimate_bias().

For each design condition (combination of n_person, n_rater, n_criterion, raters_per_person), the function:

1. Generates synthetic data with simulate_mfrm_data()

2. Injects one known Group \times Criterion DIF effect (dif_effect logits added to the focal group on the target criterion)

3. Injects one known Rater \times Criterion interaction-bias effect (bias_effect logits)

4. Fits and diagnoses the MFRM

5. Runs analyze_dff() and estimate_bias()

6. Records whether the injected signals were detected or screen-positive

Detection criteria: A DIF signal is counted as "detected" when the target contrast has p < dif_p_cut and, when an absolute contrast cutoff is in force, |\mathrm{Contrast}| \ge dif_abs_cut. For dif_method = "refit", dif_abs_cut is interpreted on the logit scale. For dif_method = "residual", the residual-contrast screening result is used and the default is to rely on the significance test alone.

Bias results are different: estimate_bias() reports t and Prob. as screening metrics rather than formal inferential quantities. Here, a bias cell is counted as screen-positive only when those screening metrics are available and satisfy p < bias_p_cut and |t| \ge bias_abs_t.

Power is the proportion of replications in which the target signal was correctly detected. For DIF this is a conventional power summary. For bias, the primary summary is BiasScreenRate, a screening hit rate rather than formal inferential power.

False-positive rate is the proportion of non-target cells that were incorrectly flagged. For DIF this is interpreted in the usual testing sense. For bias, BiasScreenFalsePositiveRate is a screening rate and should not be read as a calibrated inferential alpha level.

Default effect sizes: dif_effect = 0.6 logits corresponds to a moderate criterion-linked differential-functioning effect; bias_effect = -0.8 logits represents a substantial rater-criterion interaction. Adjust these to match the smallest effect size of practical concern for your application.

This is again a parametric simulation study. The function does not estimate a new design directly from one observed dataset. Instead, it evaluates detection or screening behavior under user-specified design conditions and known injected signals.

If you want to approximate a real study, choose the design grid and simulation settings so that they reflect the empirical context of interest. For example, you may set n_person, n_rater, n_criterion, raters_per_person, and the latent-spread arguments to values motivated by an existing assessment program, then study how operating characteristics change as those design settings vary.

When sim_spec is supplied, the function uses it as the explicit data-generating mechanism for the latent spreads, thresholds, and assignment archetype, while still injecting the requested target DIF and bias effects for each design condition.

Value

An object of class mfrm_signal_detection with:

• design_grid: evaluated design conditions

• results: replicate-level detection results

• rep_overview: run-level status and timing

• settings: signal-analysis settings

• ademp: simulation-study metadata (aims, DGM, estimands, methods, performance measures)

References

The simulation logic follows the general Monte Carlo / operating-characteristic framework described by Morris, White, and Crowther (2019) and the ADEMP-oriented planning/reporting guidance summarized for psychology by Siepe et al. (2024). In mfrmr, evaluate_mfrm_signal_detection() is a many-facet screening helper specialized to DIF and interaction-bias use cases; it is not a direct implementation of one published many-facet Rasch simulation design.

• Morris, T. P., White, I. R., & Crowther, M. J. (2019). Using simulation studies to evaluate statistical methods. Statistics in Medicine, 38(11), 2074-2102.

• Siepe, B. S., Bartos, F., Morris, T. P., Boulesteix, A.-L., Heck, D. W., & Pawel, S. (2024). Simulation studies for methodological research in psychology: A standardized template for planning, preregistration, and reporting. Psychological Methods.

See Also

simulate_mfrm_data(), evaluate_mfrm_design(), analyze_dff(), analyze_dif(), estimate_bias()

Examples

sig_eval <- suppressWarnings(evaluate_mfrm_signal_detection(
  n_person = 20,
  n_rater = 3,
  n_criterion = 3,
  raters_per_person = 2,
  reps = 1,
  maxit = 10,
  bias_max_iter = 1,
  seed = 123
))
s_sig <- summary(sig_eval)
s_sig$detection_summary[, c("n_person", "DIFPower", "BiasScreenRate")]

Export MFRM results to CSV files

Description

Writes tidy CSV files suitable for import into spreadsheet software or further analysis in other tools.

Usage

export_mfrm(
  fit,
  diagnostics = NULL,
  output_dir = ".",
  prefix = "mfrm",
  tables = c("person", "facets", "summary", "steps", "measures"),
  overwrite = FALSE
)

Arguments

Value

Invisibly, a data.frame listing written files with columns Table and Path.

Exported files

{prefix}_person_estimates.csv

Person ID, Estimate, SD.

{prefix}_facet_estimates.csv

Facet, Level, Estimate, and optionally SE, Infit, Outfit, PTMEA when diagnostics supplied.

{prefix}_fit_summary.csv

One-row model summary.

{prefix}_step_parameters.csv

Step/threshold parameters.

{prefix}_measures.csv

Full measures table (requires diagnostics).

Interpreting output

The returned data.frame tells you exactly which files were written and where. This is convenient for scripted pipelines where the output directory is created on the fly.

Typical workflow

1. Fit a model with fit_mfrm().

2. Optionally compute diagnostics with diagnose_mfrm() when you want enriched facet or measures exports.

3. Call export_mfrm(...) and inspect the returned Path column.

See Also

fit_mfrm, diagnose_mfrm, as.data.frame.mfrm_fit

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", model = "RSM", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
out <- export_mfrm(
  fit,
  diagnostics = diag,
  output_dir = tempdir(),
  prefix = "mfrmr_example",
  overwrite = TRUE
)
out$Table

Export an analysis bundle for sharing or archiving

Description

Export an analysis bundle for sharing or archiving

Usage

export_mfrm_bundle(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  population_prediction = NULL,
  unit_prediction = NULL,
  plausible_values = NULL,
  output_dir = ".",
  prefix = "mfrmr_bundle",
  include = c("core_tables", "checklist", "dashboard", "apa", "anchors", "manifest",
    "visual_summaries", "predictions", "script", "html"),
  facet = NULL,
  include_person_anchors = FALSE,
  overwrite = FALSE,
  zip_bundle = FALSE,
  zip_name = NULL
)

Arguments

Details

This function is the package-native counterpart to the app's download bundle. It reuses existing mfrmr helpers instead of reimplementing estimation or diagnostics.

Value

A named list with class mfrm_export_bundle.

Choosing exports

The include argument lets you assemble a bundle for different audiences:

• "core_tables" for analysts who mainly want CSV output.

• "manifest" for a compact analysis record.

• "script" for reproducibility and reruns.

• "html" for a light, shareable summary page.

• "visual_summaries" when you want warning maps or residual PCA summaries to travel with the bundle.

Recommended presets

Common starting points are:

• minimal tables: include = c("core_tables", "manifest")

• reporting bundle: include = c("core_tables", "checklist", "dashboard", "html")

• archival bundle: include = c("core_tables", "manifest", "script", "visual_summaries", "html")

Written outputs

Depending on include, the exporter can write:

• core CSV tables via export_mfrm()

• checklist CSVs via reporting_checklist()

• facet-dashboard CSVs via facet_quality_dashboard()

• APA text files via build_apa_outputs()

• anchor CSV via make_anchor_table()

• manifest CSV/TXT via build_mfrm_manifest()

• visual warning/summary artifacts via build_visual_summaries()

• prediction/forecast CSVs via predict_mfrm_population(), predict_mfrm_units(), and sample_mfrm_plausible_values()

• a package-native replay script via build_mfrm_replay_script()

• a lightweight HTML report that bundles the exported tables/text

Interpreting output

The returned object reports both high-level bundle status and the exact files written. In practice, bundle$summary is the quickest sanity check, while bundle$written_files is the file inventory to inspect or hand off to other tools.

Typical workflow

1. Fit a model and compute diagnostics once.

2. Decide whether the audience needs tables only, or also a manifest, replay script, and HTML summary.

3. Call export_mfrm_bundle() with a dedicated output directory.

4. Inspect bundle$written_files or open the generated HTML file.

See Also

build_mfrm_manifest(), build_mfrm_replay_script(), export_mfrm(), reporting_checklist()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score",
                method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
bundle <- export_mfrm_bundle(
  fit,
  diagnostics = diag,
  output_dir = tempdir(),
  prefix = "mfrmr_bundle_example",
  include = c("core_tables", "manifest", "script", "html"),
  overwrite = TRUE
)
bundle$summary[, c("FilesWritten", "HtmlWritten", "ScriptWritten")]
head(bundle$written_files)

Derive a simulation specification from a fitted MFRM object

Description

Derive a simulation specification from a fitted MFRM object

Usage

extract_mfrm_sim_spec(
  fit,
  assignment = c("auto", "crossed", "rotating", "resampled", "skeleton"),
  latent_distribution = c("normal", "empirical"),
  source_data = NULL,
  person = NULL,
  group = NULL
)

Arguments

Details

extract_mfrm_sim_spec() uses a fitted model as a practical starting point for later simulation studies. It extracts:

• design counts from the fitted data

• empirical spread of person and facet estimates

• optional empirical support values for semi-parametric draws

• fitted threshold values

• either a simplified assignment summary ("crossed" / "rotating"), empirical resampled assignment profiles ("resampled"), or an observed response skeleton ("skeleton", optionally carrying Group/Weight)

This is intended as a fit-derived parametric starting point, not as a claim that the fitted object perfectly recovers the true data-generating mechanism. Users should review and, if necessary, edit the returned specification before using it for design planning.

If you want to carry person-level group labels into a fit-derived observed response skeleton, provide the original source_data together with person and group. Group labels are treated as person-level metadata and are checked for one-label-per-person consistency before being merged.

Value

An object of class mfrm_sim_spec.

Interpreting output

The returned object is a simulation specification, not a prediction about one future sample. It captures one convenient approximation to the observed design and estimated spread in the fitted run.

See Also

build_mfrm_sim_spec(), simulate_mfrm_data()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 15)
spec <- extract_mfrm_sim_spec(fit, latent_distribution = "empirical")
spec$assignment
spec$model
head(spec$threshold_table)

Facet-quality dashboard for facet-level screening

Description

Build a compact dashboard for one facet at a time, combining facet severity, misfit, central-tendency screening, and optional bias counts.

Usage

facet_quality_dashboard(
  fit,
  diagnostics = NULL,
  facet = NULL,
  bias_results = NULL,
  severity_warn = 1,
  misfit_warn = 1.5,
  central_tendency_max = 0.25,
  bias_count_warn = 1L,
  bias_abs_t_warn = 2,
  bias_abs_size_warn = 0.5,
  bias_p_max = 0.05
)

Arguments

Details

The dashboard screens individual facet elements across four complementary criteria:

• Severity: elements with |\mathrm{Estimate}| > severity_warn logits are flagged as unusually harsh or lenient.

• Misfit: elements with Infit or Outfit MnSq outside [1/misfit_warn,\;misfit_warn] (default 0.67–1.5) are flagged.

• Central tendency: elements with |\mathrm{Estimate}| < central_tendency_max logits are flagged. Near-zero estimates may indicate a rater who avoids extreme categories, producing artificially narrow score ranges.

• Bias: elements involved in \ge bias_count_warn screen-positive interaction cells (from estimate_bias()) are flagged.

A flag density score counts how many of the four criteria each element triggers. Elements flagged on multiple criteria warrant priority review (e.g., rater retraining, data exclusion).

Default thresholds are designed for moderate-stakes rating contexts. Adjust for your application: stricter thresholds for high-stakes certification, more lenient for formative assessment.

Value

An object of class mfrm_facet_dashboard (also inheriting from mfrm_bundle and list). The object summarizes one target facet: overview reports the facet-level screening totals, summary provides aggregate estimates and flag counts, detail contains one row per facet level with the computed screening indicators, ranked orders levels by review priority, flagged keeps only levels requiring follow-up, bias_sources records which bias-result bundles contributed to the counts, settings stores the resolved thresholds, and notes gives short interpretation messages about how to read the dashboard.

Output

The returned object is a bundle-like list with class mfrm_facet_dashboard and components such as:

• overview: one-row structural overview

• summary: one-row screening summary

• detail: level-level detail table

• ranked: detail ordered by flag density / severity

• flagged: flagged levels only

• bias_sources: per-bundle bias aggregation metadata

• settings: resolved threshold settings

• notes: short interpretation notes

See Also

diagnose_mfrm(), estimate_bias(), plot_qc_dashboard()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
dash <- facet_quality_dashboard(fit, diagnostics = diag)
summary(dash)

Build a facet statistics report (preferred alias)

Description

Build a facet statistics report (preferred alias)

Usage

facet_statistics_report(
  fit,
  diagnostics = NULL,
  metrics = c("Estimate", "Infit", "Outfit", "SE"),
  ruler_width = 41,
  distribution_basis = c("both", "sample", "population"),
  se_mode = c("both", "model", "fit_adjusted")
)

Arguments

Details

summary(out) is supported through summary(). plot(out) is dispatched through plot() for class mfrm_facet_statistics (type = "means", "sds", "ranges").

Value

A named list with facet-statistics components. Class: mfrm_facet_statistics.

Interpreting output

• facet-level means/SD/ranges of selected metrics (Estimate, fit indices, SE).

• fixed-width ruler rows (M/S/Q/X) for compact profile scanning.

Typical workflow

1. Run facet_statistics_report(fit).

2. Inspect summary/ranges for anomalous facets.

3. Cross-check flagged facets with fit and chi-square diagnostics. The returned bundle now includes:

• precision_summary: facet precision/separation indices by DistributionBasis and SEMode

• variability_tests: fixed/random variability tests by facet

• se_modes: compact list of available SE modes by facet

See Also

diagnose_mfrm(), summary.mfrm_fit(), plot_facets_chisq(), mfrmr_reports_and_tables

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
out <- facet_statistics_report(fit)
summary(out)
p_fs <- plot(out, draw = FALSE)
class(p_fs)

Build facet variability diagnostics with fixed/random reference tests

Description

Build facet variability diagnostics with fixed/random reference tests

Usage

facets_chisq_table(
  fit,
  diagnostics = NULL,
  fixed_p_max = 0.05,
  random_p_max = 0.05,
  top_n = NULL
)

Arguments

Details

This helper summarizes facet-level variability with fixed and random chi-square indices for spread and heterogeneity checks.

Value

A named list with:

• table: facet-level chi-square diagnostics

• summary: one-row summary

• thresholds: applied p-value thresholds

Interpreting output

• table: facet-level fixed/random chi-square and p-value flags.

• summary: number of significant facets and overall magnitude indicators.

• thresholds: p-value criteria used for flagging.

Use this table together with inter-rater and displacement diagnostics to distinguish global facet effects from local anomalies.

Typical workflow

1. Run facets_chisq_table(fit, ...).

2. Inspect summary(chi) then facet rows in chi$table.

3. Visualize with plot_facets_chisq().

Output columns

The table data.frame contains:

Facet

Facet name.

Levels

Number of estimated levels in this facet.

MeanMeasure, SD

Mean and standard deviation of level measures.

FixedChiSq, FixedDF, FixedProb

Fixed-effect chi-square test (null hypothesis: all levels equal). Significant result means the facet elements differ more than measurement error alone.

RandomChiSq, RandomDF, RandomProb, RandomVar

Random-effect test (null hypothesis: variation equals that of a random sample from a single population). Significant result suggests systematic heterogeneity beyond sampling variation.

FixedFlag, RandomFlag

Logical flags for significance.

See Also

diagnose_mfrm(), interrater_agreement_table(), plot_facets_chisq()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
chi <- facets_chisq_table(fit)
summary(chi)
p_chi <- plot(chi, draw = FALSE)
class(p_chi)

Build a legacy-compatible output-file bundle (⁠GRAPH=⁠ / ⁠SCORE=⁠)

Description

Build a legacy-compatible output-file bundle (⁠GRAPH=⁠ / ⁠SCORE=⁠)

Usage

facets_output_file_bundle(
  fit,
  diagnostics = NULL,
  include = c("graph", "score"),
  theta_range = c(-6, 6),
  theta_points = 241,
  digits = 4,
  include_fixed = FALSE,
  fixed_max_rows = 400,
  write_files = FALSE,
  output_dir = NULL,
  file_prefix = "mfrmr_output",
  overwrite = FALSE
)

Arguments

Details

Legacy-compatible output files often include:

• graph coordinates for Table 8 curves (⁠GRAPH=⁠ / ⁠Graphfile=⁠), and

• observation-level modeled score lines (⁠SCORE=⁠-style inspection).

This helper returns both as data frames and can optionally write CSV/fixed-width text files to disk.

summary(out) is supported through summary(). plot(out) is dispatched through plot() for class mfrm_output_bundle (type = "graph_expected", "score_residuals", "obs_probability").

Value

A named list including:

• graphfile / graphfile_syntactic when "graph" is requested

• scorefile when "score" is requested

• graphfile_fixed / scorefile_fixed when include_fixed = TRUE

• written_files when write_files = TRUE

• settings: applied options

Interpreting output

• graphfile: legacy-compatible wide curve coordinates (human-readable labels).

• graphfile_syntactic: same curves with syntactic column names for programmatic use.

• scorefile: observation-level observed/expected/residual diagnostics.

• written_files: audit trail of files produced when write_files = TRUE.

For reproducible pipelines, prefer graphfile_syntactic and keep written_files in run logs.

Preferred route for new analyses

For new scripts, prefer category_curves_report() or category_structure_report() for scale outputs, then use export_mfrm_bundle() for file handoff. Use facets_output_file_bundle() only when a legacy-compatible graphfile or scorefile contract is required.

Typical workflow

1. Fit and diagnose model.

2. Generate bundle with include = c("graph", "score").

3. Validate with summary(out) / plot(out).

4. Export with write_files = TRUE for reporting handoff.

See Also

category_curves_report(), diagnose_mfrm(), unexpected_response_table(), export_mfrm_bundle(), mfrmr_reports_and_tables, mfrmr_compatibility_layer

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
out <- facets_output_file_bundle(fit, diagnostics = diagnose_mfrm(fit, residual_pca = "none"))
summary(out)
p_out <- plot(out, draw = FALSE)
class(p_out)

Build a FACETS compatibility-contract audit

Description

Build a FACETS compatibility-contract audit

Usage

facets_parity_report(
  fit,
  diagnostics = NULL,
  bias_results = NULL,
  branch = c("facets", "original"),
  contract_file = NULL,
  include_metrics = TRUE,
  top_n_missing = 15L
)

Arguments

Details

This function audits produced report components against a compatibility contract specification (inst/references/facets_column_contract.csv) and returns:

• column-level coverage per contract row

• table-level coverage summaries

• optional metric-level consistency checks

It is intended for compatibility-layer QA and regression auditing. It does not establish external validity or software equivalence beyond the specific schema/metric contract encoded in the audit file.

Coverage interpretation in overall:

• MeanColumnCoverage and MinColumnCoverage are computed across all contract rows (unavailable rows count as 0 coverage).

• MeanColumnCoverageAvailable and MinColumnCoverageAvailable summarize only rows whose source component is available.

summary(out) is supported through summary(). plot(out) is dispatched through plot() for class mfrm_parity_report (type = "column_coverage", "table_coverage", "metric_status", "metric_by_table").

Value

An object of class mfrm_parity_report with:

• overall: one-row compatibility-audit summary

• column_summary: coverage summary by table ID

• column_audit: row-level contract audit

• missing_preview: lowest-coverage rows

• metric_summary: one-row metric-check summary

• metric_by_table: metric-check summary by table ID

• metric_audit: row-level metric checks

• settings: branch/contract metadata

Interpreting output

• overall: high-level compatibility-contract coverage and metric-check pass rates.

• column_summary / column_audit: where compatibility-schema mismatches occur.

• metric_summary / metric_audit: numerical consistency checks tied to the current contract.

• missing_preview: quickest path to unresolved compatibility gaps.

Typical workflow

1. Run facets_parity_report(fit, branch = "facets").

2. Inspect summary(parity) and missing_preview.

3. Patch upstream table builders, then rerun the compatibility audit.

See Also

fit_mfrm(), diagnose_mfrm(), build_fixed_reports(), mfrmr_compatibility_layer

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
diag <- diagnose_mfrm(fit, residual_pca = "none")
parity <- facets_parity_report(fit, diagnostics = diag, branch = "facets")
summary(parity)
p <- plot(parity, draw = FALSE)

Build an adjusted-score reference table bundle

Description

Build an adjusted-score reference table bundle

Usage

fair_average_table(
  fit,
  diagnostics = NULL,
  facets = NULL,
  totalscore = TRUE,
  umean = 0,
  uscale = 1,
  udecimals = 2,
  reference = c("both", "mean", "zero"),
  label_style = c("both", "native", "legacy"),
  omit_unobserved = FALSE,
  xtreme = 0
)

Arguments

Details

This function wraps the package's adjusted-score calculations and returns both facet-wise and stacked tables. Historical display columns such as ⁠Fair(M) Average⁠ and ⁠Fair(Z) Average⁠ are retained for compatibility, and package-native aliases such as AdjustedAverage, StandardizedAdjustedAverage, ModelBasedSE, and FitAdjustedSE are appended to the formatted outputs.

Value

A named list with:

• by_facet: named list of formatted data.frames

• stacked: one stacked data.frame across facets

• raw_by_facet: unformatted internal tables

• settings: resolved options

Interpreting output

• stacked: cross-facet table for global comparison.

• by_facet: per-facet formatted tables for reporting.

• raw_by_facet: unformatted values for custom analyses/plots.

• settings: scoring-transformation and filtering options used.

Larger observed-vs-fair gaps can indicate systematic scoring tendencies by specific facet levels.

Typical workflow

1. Run fair_average_table(fit, ...).

2. Inspect summary(t12) and t12$stacked.

3. Visualize with plot_fair_average().

Output columns

The stacked data.frame contains:

Facet

Facet name for this row.

Level

Element label within the facet.

Obsvd Average

Observed raw-score average.

Fair(M) Average

Model-adjusted reference average on the reported score scale.

Fair(Z) Average

Standardized adjusted reference average.

ObservedAverage, AdjustedAverage, StandardizedAdjustedAverage

Package-native aliases for the three average columns above.

Measure

Estimated logit measure for this level.

SE

Compatibility alias for the model-based standard error.

ModelBasedSE, FitAdjustedSE

Package-native aliases for ⁠Model S.E.⁠ and ⁠Real S.E.⁠.

Infit MnSq, Outfit MnSq

Fit statistics for this level.

See Also

diagnose_mfrm(), unexpected_response_table(), displacement_table()

Examples

toy <- load_mfrmr_data("example_core")
fit <- fit_mfrm(toy, "Person", c("Rater", "Criterion"), "Score", method = "JML", maxit = 25)
t12 <- fair_average_table(fit, udecimals = 2)
t12_native <- fair_average_table(fit, reference = "mean", label_style = "native")
summary(t12)
p_t12 <- plot(t12, draw = FALSE)
class(p_t12)

Fit a many-facet Rasch model with a flexible number of facets

Description

This is the package entry point. It wraps mfrm_estimate() and defaults to method = "MML". Any number of facet columns can be supplied via facets.

Usage

fit_mfrm(
  data,
  person,
  facets,
  score,
  rating_min = NULL,
  rating_max = NULL,
  weight = NULL,
  keep_original = FALSE,
  model = c("RSM", "PCM"),
  method = c("MML", "JML", "JMLE"),
  step_facet = NULL,
  anchors = NULL,
  group_anchors = NULL,
  noncenter_facet = "Person",
  dummy_facets = NULL,
  positive_facets = NULL,
  anchor_policy = c("warn", "error", "silent"),
  min_common_anchors = 5L,
  min_obs_per_element = 30,
  min_obs_per_category = 10,
  quad_points = 15,
  maxit = 400,
  reltol = 1e-06
)

Arguments

Details

Data must be in long format (one row per observed rating event).

Value

An object of class mfrm_fit (named list) with:

• summary: one-row model summary (LogLik, AIC, BIC, convergence)

• facets$person: person estimates (Estimate; plus SD for MML)

• facets$others: facet-level estimates for each facet

• steps: estimated threshold/step parameters

• config: resolved model configuration used for estimation (includes config$anchor_audit)

• prep: preprocessed data/level metadata

• opt: raw optimizer result from stats::optim()

Model

fit_mfrm() estimates the many-facet Rasch model (Linacre, 1989). For a two-facet design (rater j, criterion i) the model is:

\ln\frac{P(X_{nij} = k)}{P(X_{nij} = k-1)} = \theta_n - \delta_j - \beta_i - \tau_k

where \theta_n is person ability, \delta_j rater severity, \beta_i criterion difficulty, and \tau_k the k-th Rasch-Andrich threshold. Any number of facets may be specified via the facets argument; each enters as an additive term in the linear predictor \eta.

With model = "RSM", thresholds \tau_k are shared across all levels of all facets. With model = "PCM", each level of step_facet receives its own threshold vector \tau_{i,k} on the package's shared observed score scale.

With method = "MML", person parameters are integrated out using Gauss-Hermite quadrature and EAP estimates are computed post-hoc. With method = "JML", all parameters are estimated jointly as fixed effects. See the "Estimation methods" section of mfrmr-package for details.

Input requirements

Minimum required columns are:

• person identifier (person)

• one or more facet identifiers (facets)

• observed score (score)

Scores are treated as ordered categories. If your observed categories do not start at 0, set rating_min/rating_max explicitly to avoid unintended recoding assumptions.

Supported model/estimation combinations:

• model = "RSM" with method = "MML" or "JML"/"JMLE"

• model = "PCM" with a designated step_facet (defaults to first facet)

Anchor inputs are optional:

• anchors should contain facet/level/fixed-value information.

• group_anchors should contain facet/level/group/group-value information. Both are normalized internally, so column names can be flexible (facet, level, anchor, group, groupvalue, etc.).

Anchor audit behavior:

• fit_mfrm() runs an internal anchor audit.

• invalid rows are removed before estimation.

• duplicate rows keep the last occurrence for each key.

• anchor_policy controls whether detected issues are warned, treated as errors, or kept silent.

Facet sign orientation:

• facets listed in positive_facets are treated as +1

• all other facets are treated as -1 This affects interpretation of reported facet measures.

Performance tips

For exploratory work, method = "JML" is usually faster than method = "MML", but it may require a larger maxit to converge on larger datasets.

For MML runs, quad_points is the main accuracy/speed trade-off:

• quad_points = 7 is a good lightweight default for quick iteration.

• quad_points = 15 gives a more stable approximation for final reporting.

Downstream diagnostics can also be staged:

• use diagnose_mfrm(fit, residual_pca = "none") for a quick first pass

• add residual PCA only when you need exploratory residual-structure evidence

Downstream diagnostics report ModelSE / RealSE columns and related reliability indices. For MML, non-person facet ModelSE values are based on the observed information of the marginal log-likelihood and person rows use posterior SDs from EAP scoring. For JML, these quantities remain exploratory approximations and should not be treated as equally formal.

Interpreting output

A typical first-pass read is:

1. fit$summary for convergence and global fit indicators.

2. summary(fit) for human-readable overviews.

3. diagnose_mfrm(fit) for element-level fit, approximate separation/reliability, and warning tables.

Typical workflow

1. Fit the model with fit_mfrm(...).

2. Validate convergence and scale structure with summary(fit).

3. Run diagnose_mfrm() and proceed to reporting with build_apa_outputs().

See Also

diagnose_mfrm(), estimate_bias(), build_apa_outputs(), mfrmr_workflow_methods, mfrmr_reporting_and_apa

Examples

toy <- load_mfrmr_data("example_core")

fit <- fit_mfrm(
  data = toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "JML",
  model = "RSM",
  maxit = 25
)
fit$summary
s_fit <- summary(fit)
s_fit$overview[, c("Model", "Method", "Converged")]
p_fit <- plot(fit, draw = FALSE)
class(p_fit)

# MML is the default:
fit_mml <- fit_mfrm(
  data = toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  model = "RSM",
  quad_points = 7,
  maxit = 25
)
summary(fit_mml)

# Next steps after fitting:
diag_mml <- diagnose_mfrm(fit_mml, residual_pca = "none")
chk <- reporting_checklist(fit_mml, diagnostics = diag_mml)
head(chk$checklist[, c("Section", "Item", "DraftReady")])

Build an inter-rater agreement report

Description

Build an inter-rater agreement report

Usage

interrater_agreement_table(
  fit,
  diagnostics = NULL,
  rater_facet = NULL,
  context_facets = NULL,
  exact_warn = 0.5,
  corr_warn = 0.3,
  include_precision = TRUE,
  top_n = NULL
)

Arguments

Details

This helper computes pairwise rater agreement on matched contexts and returns both a pair-level table and a one-row summary. The output is package-native and does not require knowledge of legacy report numbering.

Value

A named list with:

• summary: one-row inter-rater summary

• pairs: pair-level agreement table

• settings: applied options and thresholds

Interpreting output

• summary: overall agreement level, number/share of flagged pairs.

• pairs: pairwise exact agreement, correlation, and direction/size gaps.

• settings: applied facet matching and warning thresholds.

Pairs flagged by both low exact agreement and low correlation generally deserve highest calibration priority.

Typical workflow

1. Run with explicit rater_facet (and context_facets if needed).

2. Review summary(ir) and top flagged rows in ir$pairs.

3. Visualize with plot_interrater_agreement().

Output columns

The pairs data.frame contains:

Rater1, Rater2

Rater pair identifiers.

N

Number of matched-context observations for this pair.

Exact

Proportion of exact score agreements.

ExpectedExact

Expected exact agreement under chance.

Adjacent

Proportion of adjacent (+/- 1 category) agreements.

MeanDiff

Signed mean score difference (Rater1 - Rater2).

MAD

Mean absolute score difference.

Corr

Pearson correlation between paired scores.

Flag

Logical; TRUE when Exact < exact_warn or Corr < corr_warn.

OpportunityCount, ExactCount, ExpectedExactCount, AdjacentCount

Raw counts behind the agreement proportions.

The summary data.frame contains:

RaterFacet

Name of the rater facet analyzed.

TotalPairs

Number of rater pairs evaluated.

ExactAgreement

Mean exact agreement across all pairs.

AgreementMinusExpected

Observed exact agreement minus expected exact agreement.

MeanCorr

Mean pairwise correlation.

FlaggedPairs, FlaggedShare

Count and proportion of flagged pairs.

RaterSeparation, RaterReliability

Severity-spread indices for the rater facet, reported separately from agreement.