% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/help_linking_and_dff.R
\name{mfrmr_linking_and_dff}
\alias{mfrmr_linking_and_dff}
\title{mfrmr Linking and DFF Guide}
\description{
Package-native guide to checking connectedness, building anchor-based links,
monitoring drift, and screening differential facet functioning (DFF) in
\code{mfrmr}.
}
\section{Start with the linking question}{

\itemize{
\item "Is the design connected enough to support a common scale?"
Use \code{\link[=subset_connectivity_report]{subset_connectivity_report()}} and \code{plot(..., type = "design_matrix")}.
\item "Which elements can I export as anchors from an existing fit?"
Use \code{\link[=make_anchor_table]{make_anchor_table()}} and \code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}}.
\item "How do I anchor a new administration to a baseline?"
Use \code{\link[=anchor_to_baseline]{anchor_to_baseline()}}.
\item "Have common elements drifted across separately fitted waves?"
Use \code{\link[=detect_anchor_drift]{detect_anchor_drift()}} and \code{\link[=plot_anchor_drift]{plot_anchor_drift()}}.
\item "Can I synthesize anchor review, drift, and chain evidence into one review?"
Use \code{\link[=build_linking_review]{build_linking_review()}}.
\item "Do specific facet levels function differently across groups?"
Use \code{\link[=analyze_dff]{analyze_dff()}}, \code{\link[=plot_dif_heatmap]{plot_dif_heatmap()}}, and \code{\link[=plot_dif_summary]{plot_dif_summary()}}.
}
}

\section{Recommended linking route}{

\enumerate{
\item Fit with \code{\link[=fit_mfrm]{fit_mfrm()}} and diagnose with \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.
\item Check connectedness with \code{\link[=subset_connectivity_report]{subset_connectivity_report()}}.
\item Build or review anchors with \code{\link[=make_anchor_table]{make_anchor_table()}} and
\code{\link[=review_mfrm_anchors]{review_mfrm_anchors()}}.
\item Use \code{\link[=anchor_to_baseline]{anchor_to_baseline()}} when you need to place raw new data onto a
baseline scale.
\item Use \code{\link[=build_equating_chain]{build_equating_chain()}} only as a screened linking aid across
already fitted waves.
\item Use \code{\link[=detect_anchor_drift]{detect_anchor_drift()}} for stability monitoring on separately fitted
waves.
\item Use \code{\link[=build_linking_review]{build_linking_review()}} when you need one operational synthesis
object rather than separate anchor/drift/chain tables.
\item Run \code{\link[=analyze_dff]{analyze_dff()}} only after checking connectivity and common-scale
evidence.
}
}

\section{Which helper answers which task}{

\describe{
\item{\code{\link[=subset_connectivity_report]{subset_connectivity_report()}}}{Summarizes connected subsets,
bottleneck facets, and design-matrix coverage.}
\item{\code{\link[=make_anchor_table]{make_anchor_table()}}}{Extracts reusable anchor candidates from a fit.}
\item{\code{\link[=anchor_to_baseline]{anchor_to_baseline()}}}{Anchors new raw data to a baseline fit and
returns anchored diagnostics plus a consistency check against the baseline
scale.}
\item{\code{\link[=detect_anchor_drift]{detect_anchor_drift()}}}{Compares fitted waves directly to flag
unstable anchor elements.}
\item{\code{\link[=build_equating_chain]{build_equating_chain()}}}{Accumulates screened pairwise links across
a series of administrations or forms.}
\item{\code{\link[=build_linking_review]{build_linking_review()}}}{Synthesizes anchor review, drift, and
screened-chain evidence into one operational review surface.}
\item{\code{\link[=analyze_dff]{analyze_dff()}}}{Screens differential facet functioning with residual
or refit methods, using screening-only language unless linking and
precision support stronger interpretation.}
}
}

\section{Practical linking rules}{

\itemize{
\item Check connectedness before interpreting subgroup or wave differences.
\item Use DFF outputs as screening results when common-scale linking is weak.
\item Always name the facet, facet level, and group pair involved in a DFF
contrast. A generic "DIF exists" statement is not interpretable in a
many-facet design.
\item Residual-method DFF classifications are screening labels. ETS A/B/C
labels require refit output whose \code{ClassificationSystem} is \code{"ETS"}.
\item Treat drift flags as prompts for review, not automatic evidence that an
anchor must be removed.
\item Treat \code{LinkSupportAdequate = FALSE} as a weak-link warning: at least one
linking facet retained fewer than 5 common elements after screening.
\item Rebuild anchors from a defensible baseline rather than chaining unstable
links by hand.
}
}

\section{Typical workflow}{

\itemize{
\item Cross-sectional linkage review:
\code{\link[=fit_mfrm]{fit_mfrm()}} -> \code{\link[=diagnose_mfrm]{diagnose_mfrm()}} -> \code{\link[=subset_connectivity_report]{subset_connectivity_report()}} ->
\code{plot(..., type = "design_matrix")}.
\item Baseline placement review:
\code{\link[=make_anchor_table]{make_anchor_table()}} -> \code{\link[=anchor_to_baseline]{anchor_to_baseline()}} -> \code{\link[=diagnose_mfrm]{diagnose_mfrm()}}.
\item Multi-wave drift review:
fit each wave separately -> \code{\link[=detect_anchor_drift]{detect_anchor_drift()}} ->
\code{\link[=build_linking_review]{build_linking_review()}} -> \code{\link[=plot_anchor_drift]{plot_anchor_drift()}}.
\item Group comparison route:
\code{\link[=subset_connectivity_report]{subset_connectivity_report()}} -> \code{\link[=analyze_dff]{analyze_dff()}} ->
\code{\link[=dif_report]{dif_report()}} -> \code{\link[=plot_dif_heatmap]{plot_dif_heatmap()}} / \code{\link[=plot_dif_summary]{plot_dif_summary()}}.
}
}

\section{Companion guides}{

\itemize{
\item For visual follow-up, see \link{mfrmr_visual_diagnostics}.
\item For report/table selection, see \link{mfrmr_reports_and_tables}.
\item For end-to-end routes, see \link{mfrmr_workflow_methods}.
\item For a longer walkthrough, see
\code{vignette("mfrmr-linking-and-dff", package = "mfrmr")}.
}
}

\examples{
\donttest{
toy <- load_mfrmr_data("example_bias")
fit <- fit_mfrm(
  toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  method = "MML",
  quad_points = 7,
  maxit = 30
)
diag <- diagnose_mfrm(fit, residual_pca = "none", diagnostic_mode = "both")

subsets <- subset_connectivity_report(fit, diagnostics = diag)
subsets$summary[, c("Subset", "Observations", "ObservationPercent")]

dff <- analyze_dff(fit, diag, facet = "Rater", group = "Group", data = toy)
head(dff$dif_table[, c("Level", "Group1", "Group2",
                       "Classification", "ClassificationSystem")])
}

}
