% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simulate.R
\name{simulate_rasch}
\alias{simulate_rasch}
\title{Simulate person-by-item Rasch data with dial-in misfit}
\usage{
simulate_rasch(
  n_persons = 500,
  n_items = 20,
  model = c("dichotomous", "PCM", "RSM"),
  n_categories = 3,
  theta_mean = 0,
  theta_sd = 1,
  theta_dist = "normal",
  difficulty = c(-2.5, 2.5),
  threshold_spread = 1.2,
  discrimination = 1,
  guessing = 0,
  second_dim = NULL,
  dependence = NULL,
  dif = NULL,
  careless = 0,
  response_style = NULL,
  speeded = 0,
  disordered = NULL,
  n_groups = 1,
  missing = 0,
  seed = NULL
)
}
\arguments{
\item{n_persons, n_items}{Sample size and test length.}

\item{model}{\code{"dichotomous"}, \code{"PCM"}, or \code{"RSM"}. Under
\code{"RSM"} every item shares one category-threshold pattern (items
differ by location only); under \code{"PCM"} each item's threshold
spacings and span are drawn afresh, as the partial credit model allows.}

\item{n_categories}{Response categories for polytomous models (>= 3).}

\item{theta_mean, theta_sd, theta_dist}{Person distribution: mean, SD, and
shape (\code{"normal"}, \code{"uniform"}, \code{"skew"}, \code{"bimodal"}).}

\item{difficulty}{Two numbers giving the item-location range (evenly
spaced), or a length-\code{n_items} vector of locations.}

\item{threshold_spread}{Half-range of the category thresholds about each
item location (polytomous).}

\item{discrimination}{Scalar or length-\code{n_items}: the slope of each
item. Values above 1 over-discriminate (Guttman-like, negative fit
residual); below 1 under-discriminate (noisy, positive residual). Feeds
infit/outfit and the item-fit F.}

\item{guessing}{Scalar or length-\code{n_items} lower asymptote
(dichotomous): low-ability persons answer correctly by chance. Feeds
\code{\link{tailored_analysis}}.}

\item{second_dim}{\code{NULL}, or \code{list(items=, rho=)}: the named items
load on a second trait correlated \code{rho} with the first. Feeds
\code{\link{dimensionality_test}}.}

\item{dependence}{\code{NULL}, or \code{list(pairs=, strength=)}: each pair's
second item responds partly to the first (response dependence). Feeds
\code{\link{residual_correlations}} / \code{\link{dependence_magnitude}}.}

\item{dif}{\code{NULL}, or \code{list(items=, uniform=, nonuniform=)}: the
named items function differently for the last person group -- a location
shift (\code{uniform}) and/or a slope change (\code{nonuniform}). Needs
\code{n_groups >= 2}. Feeds \code{\link{dif_anova}} / \code{\link{dif_size}}.}

\item{careless}{Proportion of persons who answer at random (person misfit;
feeds person infit/outfit).}

\item{response_style}{\code{NULL}, or \code{list(type=, prop=, strength=)}
with \code{type} \code{"extreme"} or \code{"middle"}: a proportion
\code{prop} of persons favour the end (or middle) categories regardless
of the trait, with distortion \code{strength} (default 1.6) on the
log-probability scale (polytomous; feeds the category diagnostics and
person fit).}

\item{speeded}{Proportion not-reached at the last item: a growing tail of
missing responses over the final items, as under time pressure (feeds the
item statistics and the missingness pattern).}

\item{disordered}{\code{NULL} or item names/indices given disordered
thresholds (polytomous; feeds the threshold diagnostics).}

\item{n_groups}{Number of equal person groups (a \code{group} factor column
is added when > 1, for DIF).}

\item{missing}{Proportion of responses set missing (completely at random).}

\item{seed}{Optional RNG seed.}
}
\value{
A data frame of class \code{"rasch_sim"} (item columns
  \code{I01}..., an \code{id} column, and a \code{group} column when
  grouped), with \code{attr(x, "truth")} holding the generating parameters
  and the planted departures.
}
\description{
Generates dichotomous or polytomous (partial credit / rating scale) data
from the Rasch model, with optional, individually controllable departures
from it -- each of which the package's matching diagnostic is built to
detect. The result is a data frame ready for \code{\link{rasch}}, with the
true parameters attached as \code{attr(x, "truth")}.
}
\examples{
# a clean scale with one over-discriminating item and one DIF item
d <- simulate_rasch(400, 12, discrimination = c(3, rep(1, 11)),
                    dif = list(items = "I06", uniform = 1), n_groups = 2,
                    seed = 1)
fit <- rasch(d, id = "id", factors = "group")
fit$items[c("item", "infit_ms", "outfit_ms")]   # item 1 misfits
dif_anova(fit)$summary                           # item 6 flags
}
