choosing-item-parameters vignette
(vignette("choosing-item-parameters")) — deeper reference for the
three item-parameter specification workflows introduced in the
getting-started vignette: import from a prior mirt fit (with a
slope-intercept-to-IRT conversion worked example) or a CSV / Excel
parameter table; domain-typical preset values for cognitive ability,
personality, clinical, and achievement assessments with cited
reference ranges; and hypothesized / content-based specification
with explicit translation from item-review judgements to
distribution arguments. eval=TRUE knitr engine; no new exported
helpers in this release.irtsim getting-started vignette (vignette("irtsim"))
walking a stranger from "I need to plan an IRT study" through to
recommended_n(). The vignette builds live (eval=TRUE) so it
cannot drift from the package API. Three item-parameter
specification paths are demonstrated: by hand, via
irt_params_2pl(), and from a prior mirt calibration.irt_design() now aborts with an informative error if
n_factors != 1. Multidimensional IRT support is planned for
v0.4.0; until then, the parameter is retained on the design for
forward compatibility but silently accepting n_factors > 1
produced a cryptic mirt internal error downstream. The new abort
fires up front and points users at the planned support.recommended_n() gains an aggregate parameter
("max" / "mean" / "median" / "none", default "max"). The
default return is now an integer scalar — the smallest sample size
that powers every item/param at the requested threshold — with a
details attribute carrying the per-item data frame plus
aggregate, criterion, and threshold attributes. "mean" and
"median" round up via ceiling() so the recommendation never
falls below the central tendency. Pass aggregate = "none" to
recover the previous per-item data frame return. Behavior
change: the default return shape changed from a per-item data
frame to a scalar; closes the footgun where users could under-power
by forgetting to take max() across items.paper-reproduction-gaps vignette. Its content was a
scorecard of paper Examples 2 and 3 reproduction gaps that pointed
at deferred objectives (Obj 30/31). Those objectives are now
superseded by a planned pluggable fit_fn / extract_fn hook
(Obj 39, targeted for v0.3.0); the standalone gaps vignette no
longer reflects the roadmap. Cross-references to it from
paper-example-2-mcar and paper-example-3-grm have also been
removed.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.Initial CRAN release.
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."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 matrixmse), root mean squared error (rmse), bias, absolute bias, standard error (se), empirical coverage, Monte Carlo SE of MSE (mcse_mse).R/criterion_registry.R.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.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.irt_simulate(parallel = TRUE) dispatches iterations across workers via future.apply::future_lapply().parallel setting) guaranteed. Cross-mode results differ because serial uses Mersenne-Twister and parallel uses L'Ecuyer-CMRG substreams — both statistically valid.future::plan().cli::cli_progress_bar() replaces cat()-based progress reporting (suppressible with progress = FALSE).cli::cli_abort() error messages with valid-option enumerations for invalid model, criterion, missing mechanism, and estimation_model arguments.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.cli, future.apply, ggplot2, mirt, rlangfuture, knitr, R.rsp, rmarkdown, scales, testthatSchroeders, 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