---
title: "Many-facet Rasch measurement"
author: "Josh 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)
fit <- rasch_mfrm(d, person = "person", item = "item", score = "score",
                  facets = "rater")
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
facet level and withholds probabilities when that level 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.

## 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.)