% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/btl-independence.R
\name{judge_pair_surprise}
\alias{judge_pair_surprise}
\title{Unexpected judgements of one judge, pair by pair}
\usage{
judge_pair_surprise(fit, judge, min_n = 1L, flag_z = 1.96)
}
\arguments{
\item{fit}{A paired-comparison fit from \code{\link{btl}} with judges.}

\item{judge}{The judge to profile.}

\item{min_n}{Pairs met fewer times are shown but never flagged.}

\item{flag_z}{Absolute residual at or beyond which an upset is flagged.}
}
\value{
A list of class \code{"rasch_btl_judge_pairs"}: \code{pairs} (per
  matchup: the stronger and weaker object and their locations, the location
  \code{gap}, times met \code{n}, residual \code{z}, the \code{net_winner},
  and the \code{surprise} flag); \code{all_locations}; the \code{judge} and
  settings.
}
\description{
The comparison-level companion of \code{\link{judge_surprise}}. Each pair
the judge met is oriented to its stronger object (higher consensus
location) and given a standardised residual: \code{z < 0} means the
stronger object won less than its lead predicts -- the judge backed the
underdog. A matchup is an unexpected judgement when \code{z} falls at or
below \code{-flag_z} and the pair was seen at least \code{min_n} times, i.e.
the judge favoured the weaker object further than sampling noise explains.
}
\examples{
set.seed(1); objs <- LETTERS[1:6]; beta <- setNames(seq(-1.5, 1.5, len = 6), objs)
pr <- t(utils::combn(objs, 2))
d <- data.frame(a = rep(pr[, 1], each = 12), b = rep(pr[, 2], each = 12))
d$judge <- sample(paste0("J", 1:5), nrow(d), TRUE)
d$win <- ifelse(runif(nrow(d)) < plogis(beta[d$a] - beta[d$b]), d$a, d$b)
judge_pair_surprise(btl(d, "a", "b", "win", judge = "judge"), "J1")
}
