---
title: "Many-facet Rasch measurement"
author: "Joshua A. McGrane"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Many-facet Rasch measurement}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>",
                      fig.width = 7, fig.height = 4.2)
options(digits = 4)
```

```{r library}
library(rasch)
```

## When to use the MFRM

The many-facet Rasch model (Linacre 1989) extends the Rasch model
(Rasch 1960) to responses jointly indexed by a person, an item, and one or
more measurement facets such as rater, task, or occasion. Use `rasch_mfrm`
for such designs. A positive facet parameter denotes greater severity.
Person-group variables such as sex
or treatment are not facets: carry them as person factors and assess them with
`dif_anova`.

For facet levels $f_1,\ldots,f_Q$, the model is

$$
P(X_{ni\mathbf{f}}=x)=
\frac{\exp\left\{x\theta_n-
\sum_{k=1}^{x}\left(\delta_{ik}+\sum_{q=1}^{Q}\rho_{qf_q}\right)\right\}}
{\sum_{y=0}^{m_i}\exp\left\{y\theta_n-
\sum_{k=1}^{y}\left(\delta_{ik}+\sum_{q=1}^{Q}\rho_{qf_q}\right)\right\}}.
$$

Item thresholds have a common sum-zero origin, and the levels of each facet
sum to zero.

```{r fit}
d <- simulate_mfrm(n_persons = 60, n_items = 4, n_raters = 5,
                   rater_severity_sd = 0.7, seed = 8)
person_group <- setNames(rep(c("A", "B"), length.out = 60),
                         unique(d$person))
d$group <- person_group[d$person]
fit <- rasch_mfrm(d, person = "person", item = "item", score = "score",
                  facets = "rater", factors = "group")
fit
```

## Read the structural parameters

The model estimates item thresholds and facet severities together. Internally,
each observed item-by-facet combination is a virtual item whose thresholds are
the item thresholds shifted by the relevant facet effects. Pairwise
conditioning removes the person parameter before calibration.

```{r tables}
fit$item_effects
fit$facet_effects$rater
head(fit$item_thresholds)
```

```{r facets, fig.alt = "Rater severity estimates with confidence intervals."}
plot_facets(fit, facet = "rater")
```

The design must connect facet levels through common items and persons. A facet
nested within an item or a person-disjoint block can be confounded with item
location. `rasch_mfrm` checks the structural rank and informative
co-observation graph and stops when the decomposition is not identified.

## Item-by-facet interaction

The additive model assumes that severity differences are invariant across
items. When the design and substantive question require it, `interaction`
adds item-by-level terms with double sum-to-zero constraints.

```{r interaction}
fit_interaction <- rasch_mfrm(
  d, person = "person", item = "item", score = "score",
  facets = "rater", interaction = "rater"
)
head(fit_interaction$interaction_effects)
fit_interaction$interaction_test
```

The interaction model retains equal discrimination, but comparisons among
raters become item-dependent. A material interaction therefore qualifies the
claim of invariant rater severity rather than merely improving fit. The joint
Wald test is the primary test of the interaction family; individual cells are
exploratory and adjusted by Holm's method. The test uses the least-supported
item-by-level cell and withholds probabilities when that cell has fewer than
`max(30, q + 2)` persons or effective persons, where `q` is the omnibus degrees
of freedom.

## Diagnostics

The returned object is also a `rasch` fit in which each item-by-facet cell
enters as its own column of the response matrix (a *virtual item*), so the
fit, targeting, dependence, dimensionality, and plotting functions remain
available. MFRM margin tables additionally report an equal-cell fit residual
and a response-weighted pooled residual. Their weighting differs, so both the
design and the location of any misfit should guide interpretation.

Person factors are tested with the ordinary DIF analysis. The optional
bootstrap conditions on each person's total over the observed item-by-facet
cells and repeats both the facet calibration and the complete DIF family. Its
familywise probabilities refer to the fitted global invariant null.

```{r dif-bootstrap, eval = FALSE}
dif <- dif_anova(fit)
dif_bootstrap(fit, dif, B = 999, seed = 2026)$summary
```

## References

Linacre, J. M. (1989). *Many-Facet Rasch Measurement*. Chicago: MESA Press.

Rasch, G. (1960). *Probabilistic Models for Some Intelligence and Attainment
Tests*. Copenhagen: Danish Institute for Educational Research. (Expanded
edition, 1980, Chicago: University of Chicago Press.)