Read a FACETS fit table for fit review

Usage

read_facets_fit_table(
  file,
  facet = NULL,
  facet_map = NULL,
  format = c("auto", "delimited", "scorefile"),
  facet_col = NULL,
  level_col = NULL,
  delimiter = NULL,
  encoding = "UTF-8"
)

import_facets_fit_table(
  file,
  facet = NULL,
  facet_map = NULL,
  format = c("auto", "delimited", "scorefile"),
  facet_col = NULL,
  level_col = NULL,
  delimiter = NULL,
  encoding = "UTF-8"
)

Arguments

file: Path to a FACETS-derived fit table. A character vector of files is accepted. A directory containing score.N.txt files is also accepted.
facet: Optional facet name to assign when the file does not contain a facet column. Use this for one-facet CSV exports.
facet_map: Optional character vector mapping FACETS score-file numbers to facet names, for example c("1" = "Person", "2" = "Rater"). If unnamed, positions are used as score-file numbers.
format: File format. "auto" detects FACETS score.N.txt files from their name/header; "delimited" reads a CSV/TSV/semicolon table; and "scorefile" reads a FACETS score-file table.
facet_col, level_col: Optional explicit column names for delimited tables when automatic detection is not sufficient. For score files, level_col can override the column immediately before F-Number.
delimiter: Optional delimiter for delimited tables. If omitted, comma, tab, and semicolon are detected from the header line.
encoding: File encoding passed to readLines().

Value

A tibble with standardized fit-table columns suitable for facets_fit_review(fit, facets_fit = read_facets_fit_table(...)).

Details

This helper does not run FACETS. It reads FACETS output that already exists on disk and normalizes it to columns that facets_fit_review() can consume: Facet, Level, Estimate, SE, N, Infit, Outfit, InfitZSTD, OutfitZSTD, DF_Infit, and DF_Outfit. File imports also retain the exact reported numeric tokens (for example, InfitZSTDRaw = "2.0") and their displayed decimal counts. FACETS comparison runs should first request the highest practical output precision (for example, Udecim=8 for Measure and SE). If the resulting displayed absolute ZSTD is still exactly equal to 2, it is classified as display_boundary_indeterminate: the text file does not expose whether the unrounded value lies just below, at, or just above the conventional threshold.

Two common workflows are supported:

a FACETS score file such as score.2.txt, where the facet name is supplied by facet_map or inferred as Facet2. Both comma-delimited score files with field names and fixed-field score files using the FACETS manual column positions are supported;
a CSV/TSV table already exported from FACETS or a harmonization script, with FACETS-style column names such as Infit MnSq, Outfit ZStd, and T.Count.

After import, pass the table to facets_fit_review(). Inspect review$external_table_quality first when the FACETS export is partial, duplicated, or missing MnSq/df columns. Then inspect review$external_comparison for supplied FACETS-vs-mfrmr differences and review$df_sensitivity / review$df_sensitive for engine-vs-FACETS-style df/ZSTD convention sensitivity. Use plot(review, type = "df_sensitivity") for a quick visual check of the largest ZSTD shifts caused by df convention.

Examples

path <- tempfile(fileext = ".csv")
write.csv(
  data.frame(
    Facet = "Rater", Level = "R1", Infit = 1.02, Outfit = 0.98,
    InfitZSTD = 0.3, OutfitZSTD = -0.2, DF_Infit = 12, DF_Outfit = 13
  ),
  path,
  row.names = FALSE
)
read_facets_fit_table(path)
#> # A tibble: 1 × 27
#>   Facet Level Estimate    SE     N Infit Outfit InfitZSTD OutfitZSTD DF_Infit
#>   <chr> <chr>    <dbl> <dbl> <dbl> <dbl>  <dbl>     <dbl>      <dbl>    <dbl>
#> 1 Rater R1          NA    NA    NA  1.02   0.98       0.3       -0.2       12
#> # ℹ 17 more variables: DF_Outfit <dbl>, EstimateRaw <chr>, SERaw <chr>,
#> #   NRaw <chr>, InfitRaw <chr>, OutfitRaw <chr>, InfitZSTDRaw <chr>,
#> #   OutfitZSTDRaw <chr>, DF_InfitRaw <chr>, DF_OutfitRaw <chr>,
#> #   InfitZSTDReportedDecimals <int>, OutfitZSTDReportedDecimals <int>,
#> #   InfitZSTDDisplayState <chr>, OutfitZSTDDisplayState <chr>,
#> #   ZSTDDisplayFlagState <chr>, SourcePrecisionStatus <chr>, Source <chr>