% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-reports.R
\name{read_facets_fit_table}
\alias{read_facets_fit_table}
\alias{import_facets_fit_table}
\title{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{
\item{file}{Path to a FACETS-derived fit table. A character vector of files is
accepted. A directory containing \code{score.N.txt} files is also accepted.}

\item{facet}{Optional facet name to assign when the file does not contain a
facet column. Use this for one-facet CSV exports.}

\item{facet_map}{Optional character vector mapping FACETS score-file numbers
to facet names, for example \code{c("1" = "Person", "2" = "Rater")}. If unnamed,
positions are used as score-file numbers.}

\item{format}{File format. \code{"auto"} detects FACETS \code{score.N.txt} files from
their name/header; \code{"delimited"} reads a CSV/TSV/semicolon table; and
\code{"scorefile"} reads a FACETS score-file table.}

\item{facet_col, level_col}{Optional explicit column names for delimited
tables when automatic detection is not sufficient. For score files,
\code{level_col} can override the column immediately before \code{F-Number}.}

\item{delimiter}{Optional delimiter for delimited tables. If omitted, comma,
tab, and semicolon are detected from the header line.}

\item{encoding}{File encoding passed to \code{\link[=readLines]{readLines()}}.}
}
\value{
A tibble with standardized fit-table columns suitable for
\code{facets_fit_review(fit, facets_fit = read_facets_fit_table(...))}.
}
\description{
Read a FACETS fit table for fit review
}
\details{
This helper does not run FACETS. It reads FACETS output that already exists
on disk and normalizes it to columns that \code{\link[=facets_fit_review]{facets_fit_review()}} can consume:
\code{Facet}, \code{Level}, \code{Estimate}, \code{SE}, \code{N}, \code{Infit}, \code{Outfit}, \code{InfitZSTD},
\code{OutfitZSTD}, \code{DF_Infit}, and \code{DF_Outfit}.

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

After import, pass the table to \code{\link[=facets_fit_review]{facets_fit_review()}}. Inspect
\code{review$external_table_quality} first when the FACETS export is partial,
duplicated, or missing MnSq/df columns. Then inspect
\code{review$external_comparison} for supplied FACETS-vs-mfrmr differences and
\code{review$df_sensitivity} / \code{review$df_sensitive} for engine-vs-FACETS-style
df/ZSTD convention sensitivity. Use \code{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)
}
\seealso{
\code{\link[=facets_fit_review]{facets_fit_review()}}, \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}
}
