% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/api-estimation.R
\name{review_mfrm_anchors}
\alias{review_mfrm_anchors}
\title{Review and normalize anchor/group-anchor tables}
\usage{
review_mfrm_anchors(
  data,
  person,
  facets,
  score,
  anchors = NULL,
  group_anchors = NULL,
  weight = NULL,
  rating_min = NULL,
  rating_max = NULL,
  keep_original = FALSE,
  missing_codes = NULL,
  min_common_anchors = 5L,
  min_obs_per_element = 30,
  min_obs_per_category = 10,
  noncenter_facet = "Person",
  dummy_facets = NULL
)
}
\arguments{
\item{data}{A data.frame in long format (one row per rating event).}

\item{person}{Column name for person IDs.}

\item{facets}{Character vector of facet column names.}

\item{score}{Column name for observed score.}

\item{anchors}{Optional anchor table (Facet, Level, Anchor).}

\item{group_anchors}{Optional group-anchor table
(Facet, Level, Group, GroupValue).}

\item{weight}{Optional weight/frequency column name.}

\item{rating_min}{Optional minimum category value.}

\item{rating_max}{Optional maximum category value.}

\item{keep_original}{Keep original category values.}

\item{missing_codes}{Optional. \code{NULL} (default) is a no-op;
\code{TRUE} or \code{"default"} converts the FACETS / SPSS / SAS sentinel
set to \code{NA} on the person, facets, and score columns before
review. Supply a character vector for a custom code set.}

\item{min_common_anchors}{Minimum anchored levels per linking facet used in
recommendations (default \code{5}).}

\item{min_obs_per_element}{Minimum weighted observations per facet level used
in recommendations (default \code{30}).}

\item{min_obs_per_category}{Minimum weighted observations per score category
used in recommendations (default \code{10}).}

\item{noncenter_facet}{One facet to leave non-centered.}

\item{dummy_facets}{Facets to fix at zero.}
}
\value{
A list of class \code{mfrm_anchor_review} with:
\itemize{
\item \code{anchors}: cleaned anchor table used by estimation
\item \code{group_anchors}: cleaned group-anchor table used by estimation
\item \code{facet_summary}: counts of levels, constrained levels, and free levels
\item \code{design_checks}: observation-count checks by level/category
\item \code{thresholds}: active threshold settings used for recommendations
\item \code{issue_counts}: issue-type counts
\item \code{issues}: list of issue tables
\item \code{recommendations}: package-native anchor guidance strings
}
}
\description{
Review and normalize anchor/group-anchor tables
}
\details{
\strong{Anchoring} (also called "fixing" or scale linking) constrains selected
parameter estimates to pre-specified values, placing the current
analysis on a previously established scale.  This is essential when
comparing results across administrations, linking test forms, or
monitoring rater drift over time.

This function applies the same preprocessing and key-resolution rules
as \code{fit_mfrm()}, but returns a review object so constraints can be
checked \emph{before} estimation.  Running the review first helps avoid
estimation failures caused by misspecified or data-incompatible
anchors.

\strong{Anchor types:}
\itemize{
\item \emph{Direct anchors} fix individual element measures to specific logit
values (e.g., Rater R1 anchored at 0.35 logits).
\item \emph{Group anchors} constrain the mean of a set of elements to a
target value, allowing individual elements to vary freely around
that mean.
\item When both types overlap for the same element, the direct anchor
takes precedence.
}

\strong{Design checks} verify that each anchored element has at least
\code{min_obs_per_element} weighted observations (default 30) and each
score category has at least \code{min_obs_per_category} (default 10).
These thresholds follow standard Rasch sample-size recommendations
(Linacre, 1994).
}
\section{Interpreting output}{

\itemize{
\item \code{issue_counts}/\code{issues}: concrete data or specification problems.
\item \code{facet_summary}: constraint coverage by facet.
\item \code{design_checks}: whether anchor targets have enough observations.
\item \code{recommendations}: action items before estimation.
}
}

\section{Typical workflow}{

\enumerate{
\item Build candidate anchors (e.g., with \code{\link[=make_anchor_table]{make_anchor_table()}}).
\item Run \code{review_mfrm_anchors(...)}.
\item Resolve issues, then fit with \code{\link[=fit_mfrm]{fit_mfrm()}}.
}
}

\examples{
toy <- load_mfrmr_data("example_core")

anchors <- data.frame(
  Facet = c("Rater", "Rater"),
  Level = c("R1", "R1"),
  Anchor = c(0, 0.1),
  stringsAsFactors = FALSE
)
review <- review_mfrm_anchors(
  data = toy,
  person = "Person",
  facets = c("Rater", "Criterion"),
  score = "Score",
  anchors = anchors
)
review$issue_counts
summary(review)
p_review <- plot(review, draw = FALSE)
p_review$data$plot
}
\seealso{
\code{\link[=fit_mfrm]{fit_mfrm()}}, \code{\link[=describe_mfrm_data]{describe_mfrm_data()}}, \code{\link[=make_anchor_table]{make_anchor_table()}}
}
