# irtsim 0.1.1

CRAN resubmission. Documentation-only changes; no user-facing API or
behavior changes.

* `DESCRIPTION`: expanded all acronyms on first use (API, IRT, 1PL,
  2PL, MCAR, MAR, MSE, RMSE, SE) per CRAN reviewer request.
* `man/`: replaced `\dontrun{}` with `\donttest{}` in `irt_simulate`,
  `summary.irt_results`, `plot.irt_results`, `plot.summary_irt_results`,
  `recommended_n`, `print.irt_results`, and `print.summary_irt_results`
  examples per CRAN reviewer request. Examples remain wrapped (not
  unwrapped) because each depends on a ~300-fit `irt_simulate()` call
  that exceeds the 5-second CRAN example-execution budget.

# irtsim 0.1.0

Initial CRAN release.

## Core pipeline

* `irt_design()` specifies the data-generating IRT model (items, parameters, theta distribution).
* `irt_study()` adds study conditions (sample sizes, missing-data mechanism, optional separate estimation model).
* `irt_simulate()` runs the Monte Carlo simulation loop with deterministic seeding and optional parallelism.
* `summary()`, `plot()`, and `recommended_n()` methods extract simulation-based sample-size recommendations from `irt_results` objects.

## Supported IRT models

* 1PL (Rasch)
* 2PL
* Graded response model (GRM)

## Supported missing-data mechanisms

* `"none"` — complete data
* `"mcar"` — missing completely at random
* `"mar"` — missing at random (monotone, trait-dependent)
* `"booklet"` — structured booklet assignment with common-item overlap
* `"linking"` — two-form linked design with user-supplied linking matrix

## Performance criteria

* Mean squared error (`mse`), root mean squared error (`rmse`), bias, absolute bias, standard error (`se`), empirical coverage, Monte Carlo SE of MSE (`mcse_mse`).
* Criterion metadata (direction of improvement, display label) centralized in `R/criterion_registry.R`.
* Custom per-iteration criteria via the `criterion_fn` argument to `summary.irt_results()` — callbacks receive `estimates`, `true_value`, `ci_lower`, `ci_upper`, and `converged` and return named numeric vectors appended to `item_summary`.

## Model misspecification

* `irt_study(estimation_model = ...)` allows fitting a different IRT model than the one used to generate data (e.g., generate 2PL, fit 1PL). Compatible cross-pairs: `(1PL, 2PL)`, `(2PL, 1PL)`, same-model. GRM is not cross-compatible with dichotomous models.

## Parallelization

* `irt_simulate(parallel = TRUE)` dispatches iterations across workers via `future.apply::future_lapply()`.
* Reproducibility contract: within-mode (identical results on re-run for a given `parallel` setting) guaranteed. Cross-mode results differ because serial uses Mersenne-Twister and parallel uses L'Ecuyer-CMRG substreams — both statistically valid.
* Users control backend via `future::plan()`.

## User experience

* `cli::cli_progress_bar()` replaces `cat()`-based progress reporting (suppressible with `progress = FALSE`).
* Structured `cli::cli_abort()` error messages with valid-option enumerations for invalid model, criterion, missing mechanism, and `estimation_model` arguments.

## Documentation

* Five vignettes reproduce or extend the three examples from Schroeders and Gnambs (2025):
  * **Paper Example 1** — faithful reproduction of the linked-test design with 1PL estimation.
  * **Paper Example 1b** — extension showing bias-variance tradeoff when a 2PL-generated dataset is fit with a 1PL model.
  * **Paper Example 2** — MCAR-only partial reproduction with custom-criterion-callback feature demonstration.
  * **Paper Example 3** — GRM item parameter recovery partial reproduction.
  * **Paper reproduction status** — scorecard documenting what the current API can and cannot reproduce end-to-end.
* Vignettes are shipped as static HTML via `R.rsp::asis` because re-running the Monte Carlo simulations during package checks would exceed CRAN's build-time budget. The source `.Rmd` files and `data-raw/precompute_vignettes.R` are available in the GitHub repository for users who wish to reproduce results locally.

## Dependencies

* Imports: `cli`, `future.apply`, `ggplot2`, `mirt`, `rlang`
* Suggests: `future`, `knitr`, `R.rsp`, `rmarkdown`, `scales`, `testthat`

## Reference

Schroeders, U., and Gnambs, T. (2025). Sample size planning in item response theory: A 10-decision framework. *Advances in Methods and Practices in Psychological Science*. <https://doi.org/10.1177/25152459251314798>
