% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/btl-equating.R
\name{btl_equate}
\alias{btl_equate}
\title{Equate two paired-comparison calibrations through their common objects}
\usage{
btl_equate(fit1, fit2, alpha = 0.05, p_adjust = "holm")
}
\arguments{
\item{fit1}{A fitted object from \code{\link{btl}}: the calibration whose
scale (origin) the equating targets.}

\item{fit2}{A second \code{\link{btl}} fit, or a bank: a data frame with
columns \code{object}, \code{location}, and optionally \code{se}.}

\item{alpha}{Significance level for the (multiplicity-adjusted) drift tests.}

\item{p_adjust}{Multiple-comparison adjustment across the common objects,
passed to \code{\link[stats]{p.adjust}} (default \code{"holm"}).}
}
\value{
A list of class \code{"rasch_btl_equate"}: the comparison
  \code{table} (per common object: object, both locations and standard
  errors, their \code{difference}, the \code{shifted_difference} against the
  estimated origin, the pooled \code{se_diff}, \code{t}, raw and adjusted
  \code{p}, and the \code{drifting} flag); the estimated \code{shift} and
  its \code{shift_se}; \code{equated}, the second calibration's full object
  table re-expressed on \code{fit1}'s scale; the number of common objects
  \code{n_common}; \code{alpha}; \code{p_adjust}; and \code{notes}.
}
\description{
Compares the object locations of a Bradley-Terry-Luce fit with those of a
second fit (or a banked table of object locations), matched by object name.
The use case is standards maintenance and comparative judgement across
panels or years: the same scripts, performances, or products are judged by
different panels -- or by one panel in successive years -- and a common set
of anchor objects is carried through so that the two rounds land on a single
scale.
}
\details{
Each calibration is identified by the sum-zero constraint, but the two
constraints are imposed over \emph{different} object sets, so the origins do
not coincide even when the shared objects are unchanged: each scale is
centred on the mean of a different collection. A scale shift between the two
origins is therefore estimated by the precision-weighted mean difference
over the common objects, and each common object is then tested against the
shifted identity line. A flagged object shows drift -- a script the two
panels valued differently, or a standard that moved between years -- and
weakens the equating link; the surviving objects carry the second
calibration's whole scale onto the first (\code{loc2 + shift}).

The single shift presumes the drifting objects are a \emph{minority}. When
most of the common objects have genuinely moved, the precision-weighted
shift is pulled toward the movers and the drift tests can invert -- the
stable anchors flag as the apparent drifters. Read wholesale flagging
(several objects, one direction) as a contaminated link, not as evidence
about the individual objects; equate through a vetted anchor subset
instead. The \code{shift_se} accounts for the covariance of the location
estimates within each calibration (each is sum-zero constrained, so its
locations are not independent).
}
\examples{
set.seed(1)
beta <- setNames(seq(-2, 2, length.out = 8), paste0("O", 1:8))
sim <- function(objs) {
  pr <- t(utils::combn(objs, 2))
  d <- data.frame(a = rep(pr[, 1], each = 40), b = rep(pr[, 2], each = 40))
  d$win <- ifelse(runif(nrow(d)) < plogis(beta[d$a] - beta[d$b]), d$a, d$b)
  btl(d, "a", "b", "win")
}
eq <- btl_equate(sim(paste0("O", 1:7)), sim(paste0("O", 2:8)))
eq$table
}
\references{
Bramley, T. (2007). Paired comparison methods. In P. Newton,
  J. Baird, H. Goldstein, H. Patrick, & P. Tymms (Eds.), \emph{Techniques
  for monitoring the comparability of examination standards} (pp. 246-294).
  London: Qualifications and Curriculum Authority.
}
