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

\item{judge}{The judge to profile (a value of the fit's judge column).}

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

\item{flag_z}{Absolute residual at or beyond which a contrary judgement is
flagged unexpected.}
}
\value{
A list of class \code{"rasch_btl_judge"}: \code{objects} (per object
  met: location, times met \code{n}, residual \code{z}, \code{surprise} flag
  and its \code{type}); \code{all_locations} (every object, for orientation);
  the \code{judge} and settings.
}
\description{
The paired-comparison counterpart of the kidmap. A judge has no ability to
condition on, so the reference is the consensus object scale (the pooled
locations). For the nominated judge, each object it met is given a
standardised residual oriented to the object -- how much more (\code{z > 0},
over-rated) or less (\code{z < 0}, under-rated) that judge favoured it than
its consensus location predicts. A surprise is an object the judge treated
against its standing: a strong object under-rated, or a weak object
over-rated (residual opposite in sign to the location), beyond
\code{flag_z} and seen at least \code{min_n} times.
}
\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_surprise(btl(d, "a", "b", "win", judge = "judge"), "J1")
}
