% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/mfrm.R
\name{rasch_mfrm}
\alias{rasch_mfrm}
\title{Fit a many-facet Rasch model}
\usage{
rasch_mfrm(
  data,
  person,
  item = NULL,
  score = NULL,
  facets,
  items = NULL,
  n_groups = NULL,
  adjust_N = NA,
  na_codes = -1,
  interaction = NULL,
  maxit = 60,
  tol = 1e-08
)
}
\arguments{
\item{data}{Long-format data frame.}

\item{person}{Name of the person identifier column.}

\item{item}{Name of the item column.}

\item{score}{Name of the integer score column (categories from 0; gaps are
collapsed per item with a note).}

\item{facets}{Character vector naming one or more facet columns (for
example a rater column).}

\item{items}{Optional character vector of item score columns for data in
wide format: one row per person-by-facet combination (for example one
row per script per rater) with one column per item or criterion. The
long form (\code{item} + \code{score}) remains available for data
where the facet varies within items.}

\item{n_groups}{Number of class intervals for the item-trait chi-square;
\code{NULL} (the default) applies the class-interval rule of Andrich and
Marais (2019, ch. 15) (at least 50
non-extreme persons per interval, at most 10 intervals, at least 2).}

\item{adjust_N}{Optional reference sample size for the chi-square.}

\item{na_codes}{Score values to read as missing (default \code{-1}); any
negative score is also treated as missing.}

\item{interaction}{Optional name of one facet to interact with the items
(interactive facet mode). Adds item-by-facet terms
\code{gamma[item, level]} with double sum-to-zero constraints on top of
the additive severities, so each level may be more or less severe on
particular items; estimates are returned in \code{interaction_effects}.
The interactive model remains in the Rasch class (all discriminations
equal one and the parameters are additive), but a significant
interaction qualifies specific objectivity in practice: comparisons of
the interacting facet's levels become item-dependent, which is itself
the substantive finding.}

\item{maxit, tol}{Newton-Raphson iteration cap and convergence tolerance.}
}
\value{
An object of classes \code{"rasch_mfrm"} and \code{"rasch"}. In
  addition to every component of a \code{\link{rasch}} fit (computed over
  the virtual items), it carries \code{facet_effects} (per facet: level,
  severity, standard error, observation count, pooled fit),
  \code{item_effects} (underlying item locations and pooled fit),
  \code{item_thresholds} (the structural \code{delta_ik} with standard
  errors), and \code{facet_spec}. Two fit residuals are reported per
  facet level and per underlying item. \code{fit_resid} is the
  facet-margin statistic of the published three-facet fit tables
  (Andrich and Marais 2019, ch. 26 and app. C), the mean of the
  constituent virtual items'
  fit residuals; it weighs each virtual item equally, so an erratic level
  shows the average of its per-item misfit. \code{fit_resid_pooled} is
  the log-of-mean-square statistic summed over the margin's
  observed cells of non-extreme persons, with its degrees of freedom in
  \code{df_fit}; it weighs each response equally and is the more
  powerful statistic when misfit is spread evenly over the level's
  cells.
}
\description{
Estimates the many-facet Rasch model (Linacre 1989) for long-format data
in which each row is one scored response carrying a person, an item, a
score, and one or more facet levels (for example the rater). Every
item-by-facet combination becomes a virtual item whose thresholds are the
item's thresholds shifted by the facet severities, and the whole structure
is estimated in one pass of the pairwise conditional likelihood, in which
the person parameter cancels. Facet severities are reported with standard
errors and pooled fit statistics; the returned object is also a full
\code{\link{rasch}} fit at the virtual-item level, so every diagnostic
table and plot in the package applies to it.
}
\examples{
set.seed(1)
simP <- function(th, tau) { x <- 0:length(tau); p <- exp(x * th - c(0, cumsum(tau))); p / sum(p) }
persons <- sprintf("P\%03d", 1:120); raters <- paste0("R", 1:4)
th <- setNames(rnorm(120, 0, 1.3), persons)
rho <- setNames(c(-0.6, -0.2, 0.2, 0.6), raters)
tau <- list(A = c(-1, 1), B = c(-0.5, 1.2), C = c(-1.2, 0.4))
d <- expand.grid(person = persons, item = names(tau), rater = raters,
                 stringsAsFactors = FALSE)
d$score <- mapply(function(p, i, r)
  sample(0:2, 1, prob = simP(th[p], tau[[i]] + rho[r])), d$person, d$item, d$rater)
fit <- rasch_mfrm(d, person = "person", item = "item", score = "score",
                  facets = "rater")
fit$facet_effects$rater
}
