% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate.R
\name{simulate_btl}
\alias{simulate_btl}
\title{Simulate paired-comparison (BTL) data with dial-in misfit}
\usage{
simulate_btl(
  n_objects = 8,
  n_judges = 12,
  reps_per_pair = 25,
  model = c("dichotomous", "graded"),
  n_categories = 4,
  object_sd = 1,
  second_attribute = NULL,
  erratic_judges = 0,
  dependence = NULL,
  seed = NULL
)
}
\arguments{
\item{n_objects, n_judges}{Objects to scale and judges comparing them.}

\item{reps_per_pair}{Comparisons made of each object pair.}

\item{model}{\code{"dichotomous"} (a winner) or \code{"graded"} (a rated
margin in \code{n_categories} categories).}

\item{n_categories}{Categories for the graded model.}

\item{object_sd}{Spread of the object locations (evenly spaced, sum-zero).}

\item{second_attribute}{\code{NULL}, or \code{list(rho=)}: half the judges
rank by a second object attribute correlated \code{rho} with the first --
genuine multidimensionality. Feeds \code{\link{btl_dimensionality}} and
\code{\link{btl_transitivity}}.}

\item{erratic_judges}{Proportion of judges who choose at random. Feeds the
judge fit residual, \code{\link{btl_transitivity}} consistency, and
\code{\link{judge_surprise}}.}

\item{dependence}{\code{NULL}, or \code{list(exposure=, carry_over=)}:
within-judge order effects (a seen-before advantage and a pull from the
judge's own earlier verdicts). Adds an \code{order} column. Feeds the
dependence effects of \code{\link{btl}}.}

\item{seed}{Optional RNG seed.}
}
\value{
A data frame of class \code{"rasch_sim"}: \code{object_a},
  \code{object_b}, \code{winner} (or \code{response} when graded),
  \code{judge}, and \code{order} when dependence is planted; with
  \code{attr(x, "truth")}.
}
\description{
Generates dichotomous or graded paired comparisons from the
Bradley-Terry-Luce model, with optional departures each of which a
paired-comparison diagnostic is built to detect. The result is a data frame
ready for \code{\link{btl}}, with the truth attached.
}
\examples{
d <- simulate_btl(8, 12, erratic_judges = 0.15, seed = 1)
bt <- btl(d, "object_a", "object_b", winner = "winner", judge = "judge")
bt$judges          # the erratic judges carry large fit residuals
}
