Skip to contents

Build a FACETS compatibility-contract audit

Source: R/api-reports.R
facets_parity_report.Rd

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.

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

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").

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)
#> mfrmr Compatibility Contract Audit Summary 
#>   Class: mfrm_parity_report
#>   Components (8): overall, column_summary, column_audit, missing_preview, metric_summary, metric_by_table, metric_audit, settings
#> 
#> Compatibility audit overview
#>  Branch ContractRows AvailableRows FullMatchRows ColumnMismatches
#>  facets           54            54            54                0
#>  ColumnMismatchRate MeanColumnCoverage MinColumnCoverage
#>                   0                  1                 1
#>  MeanColumnCoverageAvailable MinColumnCoverageAvailable MetricChecks
#>                            1                          1           14
#>  MetricEvaluated MetricFailed MetricPassRate
#>               14            0              1
#> 
#> Lowest-coverage contract items: column_audit
#>  table_id         function_name object_id           component required_n
#>   Table 1 specifications_report        t1              header          6
#>   Table 1 specifications_report        t1           data_spec          2
#>   Table 1 specifications_report        t1        facet_labels          3
#>   Table 1 specifications_report        t1         output_spec          2
#>   Table 1 specifications_report        t1 convergence_control          2
#>   Table 1 specifications_report        t1      anchor_summary          4
#>   Table 2   data_quality_report        t2             summary          9
#>   Table 2   data_quality_report        t2         model_match          3
#>   Table 2   data_quality_report        t2           row_audit          2
#>   Table 2   data_quality_report        t2     category_counts          3
#>  present_n coverage available full_match status missing
#>          6        1      TRUE       TRUE  match        
#>          2        1      TRUE       TRUE  match        
#>          3        1      TRUE       TRUE  match        
#>          2        1      TRUE       TRUE  match        
#>          2        1      TRUE       TRUE  match        
#>          4        1      TRUE       TRUE  match        
#>          9        1      TRUE       TRUE  match        
#>          3        1      TRUE       TRUE  match        
#>          2        1      TRUE       TRUE  match        
#>          3        1      TRUE       TRUE  match        
#> 
#> Settings
#>              Setting
#>               branch
#>        contract_path
#>         intended_use
#>  external_validation
#>      include_metrics
#>        top_n_missing
#>        bias_included
#>                                                                                 Value
#>                                                                                facets
#>  /tmp/RtmpeUKqG2/temp_libpath1bf23e147960/mfrmr/references/facets_column_contract.csv
#>                                                          compatibility_contract_audit
#>                                                                                 FALSE
#>                                                                                  TRUE
#>                                                                                    15
#>                                                                                  TRUE
#> 
#> Notes
#>  - All contract rows reached full column coverage.All evaluated metric checks passed.
p <- plot(parity, draw = FALSE)