facets_parity_report: Build a FACETS compatibility-contract audit

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

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

fit	Output from fit_mfrm().
diagnostics	Optional output from diagnose_mfrm(). If omitted, diagnostics are computed internally with residual_pca = "none".
bias_results	Optional output from estimate_bias(). If omitted and at least two facets exist, a 2-way bias run is computed internally.
branch	Contract branch. "facets" checks legacy-compatible columns. "original" adapts branch-sensitive contracts to the package's compact naming.
contract_file	Optional path to a custom contract CSV.
include_metrics	If TRUE, run additional numerical consistency checks.
top_n_missing	Number of lowest-coverage contract rows to keep in missing_preview.

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)

mfrmr documentation built on March 31, 2026, 1:06 a.m.