Package 'irtsim'

Description

Define the data-generating model for an IRT simulation study. This captures decisions 1–3 from the Schroeders & Gnambs (2025) framework: dimensionality, item parameters, and item type.

Usage

irt_design(model, n_items, item_params, theta_dist = "normal", n_factors = 1L)

Arguments

Value

An S3 object of class irt_design (a named list) with elements model, n_items, item_params, theta_dist, and n_factors.

See Also

irt_study() to add study conditions, irt_params_2pl() and irt_params_grm() to generate item parameters.

Examples

# 1PL (Rasch) design with 20 items
design_1pl <- irt_design(
  model = "1PL",
  n_items = 20,
  item_params = list(b = seq(-2, 2, length.out = 20))
)

# 2PL design
design_2pl <- irt_design(
  model = "2PL",
  n_items = 30,
  item_params = list(
    a = rlnorm(30, 0, 0.25),
    b = seq(-2, 2, length.out = 30)
  )
)

Description

Uses the Burton (2003) formula to determine the minimum number of simulation replications needed to achieve a desired level of Monte Carlo precision.

Usage

irt_iterations(sigma, delta, alpha = 0.05)

Arguments

Details

The formula is:

$R = \lceil (z_{\alpha/2} \cdot \sigma / \delta)^2 \rceil$

where $\sigma$ is the empirical standard error of the estimand, $\delta$ is the acceptable Monte Carlo error, and $z_{\alpha/2}$ is the critical value for the desired confidence level.

Value

An integer: the minimum number of replications.

References

Burton, A., Altman, D. G., Royston, P., & Holder, R. L. (2006). The design of simulation studies in medical statistics. Statistics in Medicine, 25(24), 4279–4292. doi:10.1002/sim.2673

See Also

irt_simulate() for running the simulation with the computed number of replications.

Examples

# How many replications for MC SE of bias < 0.1
# when empirical SE of the estimand is 0.5?
irt_iterations(sigma = 0.5, delta = 0.1)

# Tighter tolerance with 99% MC confidence
irt_iterations(sigma = 0.5, delta = 0.05, alpha = 0.01)

Description

Creates a list of difficulty (b) parameters suitable for passing to irt_design() with model = "1PL". The 1PL model is Rasch-family: every item shares the same discrimination (fixed at 1), so only b is generated here — the a = 1 contract is applied downstream in the design's validate_params step.

Usage

irt_params_1pl(
  n_items,
  b_dist = "normal",
  b_mean = 0,
  b_sd = 1,
  b_range = c(-2, 2),
  seed = NULL
)

Arguments

Value

A named list with a single element b (numeric vector of length n_items). Note: no a is returned — 1PL fixes discrimination at 1 downstream rather than at generation time.

See Also

irt_params_2pl() for the free-discrimination binary alternative, irt_design() to use the generated parameters.

Examples

# Default 1PL parameters for 30 items
params <- irt_params_1pl(n_items = 30, seed = 42)

# Evenly-spaced difficulty across a wider range
params <- irt_params_1pl(n_items = 20, b_dist = "even", b_range = c(-3, 3))

Description

Creates a list of discrimination (a) and difficulty (b) parameters suitable for passing to irt_design().

Usage

irt_params_2pl(
  n_items,
  a_dist = "lnorm",
  a_mean = 0,
  a_sd = 0.25,
  b_dist = "normal",
  b_mean = 0,
  b_sd = 1,
  b_range = c(-2, 2),
  seed = NULL
)

Arguments

Value

A named list with elements a (numeric vector) and b (numeric vector), each of length n_items.

See Also

irt_params_grm() for GRM parameters, irt_design() to use the generated parameters.

Examples

# Default 2PL parameters for 30 items
params <- irt_params_2pl(n_items = 30, seed = 42)

# Evenly-spaced difficulty
params <- irt_params_2pl(n_items = 20, b_dist = "even", b_range = c(-3, 3))

Description

Creates a list of discrimination (a), difficulty (b), and guessing (c) parameters suitable for passing to irt_design() with model = "3PL".

Usage

irt_params_3pl(
  n_items,
  a_dist = "lnorm",
  a_mean = 0,
  a_sd = 0.25,
  b_dist = "normal",
  b_mean = 0,
  b_sd = 1,
  b_range = c(-2, 2),
  c_shape1 = 5,
  c_shape2 = 17,
  seed = NULL
)

Arguments

Value

A named list with elements a, b, c, each a numeric vector of length n_items.

See Also

irt_params_2pl(), irt_params_grm(), irt_design().

Examples

# Default 3PL parameters for 30 items
params <- irt_params_3pl(n_items = 30, seed = 42)

# Custom guessing distribution (e.g., 5-option items, lower chance level)
params <- irt_params_3pl(
  n_items = 30, c_shape1 = 4, c_shape2 = 16, seed = 42
)

Description

Creates a list of discrimination (a) and step (b) parameters suitable for passing to irt_design() with model = "GPCM".

Usage

irt_params_gpcm(
  n_items,
  n_categories,
  a_dist = "lnorm",
  a_mean = 0,
  a_sd = 0.25,
  b_dist = "normal",
  b_mean = 0,
  b_sd = 1,
  b_range = c(-2, 2),
  step_dispersion = 1,
  seed = NULL
)

Arguments

Details

The Generalized Partial Credit Model (Muraki, 1992) is partial-credit family — like the Partial Credit Model, step parameters within each item are NOT required to be ordered (the defining contrast with the Graded Response Model). Unlike PCM, GPCM allows per-item discrimination: a is a free positive vector rather than fixed at 1. See irt_params_pcm() for the Rasch-family alternative.

Value

A named list with elements:

a

Positive numeric vector of length n_items.

b

Numeric matrix with n_items rows and n_categories - 1 columns. Steps are NOT sorted within row.

See Also

irt_params_pcm() for the Rasch-family (a fixed at 1) alternative, irt_params_grm() for the ordered-threshold polytomous model, irt_design() to use the generated parameters.

Examples

# GPCM parameters: 15 items, 4 response categories
params <- irt_params_gpcm(n_items = 15, n_categories = 4, seed = 42)

# Tighter within-item step spread and a wider discrimination distribution
params <- irt_params_gpcm(
  n_items = 15, n_categories = 4,
  a_sd = 0.50, step_dispersion = 0.5, seed = 42
)

Description

Creates a list of discrimination (a) and threshold (b) parameters suitable for passing to irt_design() with model = "GRM".

Usage

irt_params_grm(
  n_items,
  n_categories,
  a_dist = "lnorm",
  a_mean = 0,
  a_sd = 0.25,
  b_mean = 0,
  b_sd = 1,
  seed = NULL
)

Arguments

Value

A named list with elements:

a

Numeric vector of length n_items.

b

Numeric matrix with n_items rows and n_categories - 1 columns. Thresholds are ordered within each row.

See Also

irt_params_2pl() for 2PL parameters, irt_design() to use the generated parameters.

Examples

# GRM parameters: 15 items, 5 response categories
params <- irt_params_grm(n_items = 15, n_categories = 5, seed = 42)

Description

Creates a list of discrimination (a, fixed at 1) and step (b) parameters suitable for passing to irt_design() with model = "PCM".

Usage

irt_params_pcm(
  n_items,
  n_categories,
  b_dist = "normal",
  b_mean = 0,
  b_sd = 1,
  b_range = c(-2, 2),
  step_dispersion = 1,
  seed = NULL
)

Arguments

Details

The Partial Credit Model (Masters, 1982) is a Rasch-family polytomous model: every item shares the same discrimination (fixed at 1), and the step parameters within each item are NOT required to be ordered. This is the defining contrast with the Graded Response Model — see irt_params_grm() for the ordered-threshold alternative.

Value

A named list with elements:

a

Numeric vector of length n_items, all 1 (Rasch family).

b

Numeric matrix with n_items rows and n_categories - 1 columns. Steps are NOT sorted within row.

See Also

irt_params_grm() for the ordered-threshold polytomous model, irt_design() to use the generated parameters.

Examples

# PCM parameters: 15 items, 4 response categories
params <- irt_params_pcm(n_items = 15, n_categories = 4, seed = 42)

# Tighter within-item step spread (steps closer to the item center)
params <- irt_params_pcm(
  n_items = 15, n_categories = 4, step_dispersion = 0.5, seed = 42
)

Description

Execute a Monte Carlo simulation study based on an irt_study specification. For each iteration and sample size, data are generated, missing values applied, the IRT model is fitted, and parameter estimates are extracted and stored.

Usage

irt_simulate(
  study,
  iterations,
  seed,
  progress = TRUE,
  parallel = FALSE,
  se = TRUE,
  compute_theta = TRUE
)

Arguments

Details

The returned irt_results object stores raw per-iteration estimates. Use summary.irt_results() to compute performance criteria (bias, MSE, RMSE, coverage, etc.) and plot.irt_results() to visualize results.

Parallelization

When parallel = TRUE, the Monte Carlo loop over iterations is parallelized via future.apply::future_lapply(). Each parallel task processes one iteration across all sample sizes sequentially.

Important: This function does NOT configure a future plan. Users must set their own plan before calling with parallel = TRUE:

library(future)
plan(multisession, workers = 4)  # or your preferred backend
results <- irt_simulate(study, iterations = 100, seed = 42, parallel = TRUE)

Without an explicit plan, future defaults to sequential execution (no parallelism).

Reproducibility contract

Reproducibility is guaranteed within a given dispatch mode, not across modes:

• Serial mode (parallel = FALSE) uses deterministic per-cell seeds under the session's default RNG kind (Mersenne-Twister). Re-running with the same base seed reproduces identical results bit-for-bit.

• Parallel mode (parallel = TRUE) delegates RNG management to future.apply::future_lapply(..., future.seed = TRUE), which assigns each iteration a formally independent L'Ecuyer-CMRG substream. Re-running with the same base seed reproduces identical results bit-for-bit across parallel runs, including across different worker counts.

• Across modes, numerical results will differ because the two paths use different RNG algorithms and different seeding strategies. Both are statistically valid; the parallel path has the stronger formal guarantee of independent substreams, which is the standard for Monte Carlo work.

Progress messages are suppressed in parallel mode (workers cannot stream to stdout safely). Set progress = FALSE in serial mode to suppress messages (they appear every 10% of iterations).

Value

An S3 object of class irt_results containing:

item_results

Data frame with per-iteration item parameter estimates (columns: iteration, sample_size, item, param, true_value, estimate, se, ci_lower, ci_upper, converged).

theta_results

Data frame with per-iteration theta recovery summaries (columns: iteration, sample_size, theta_cor, theta_rmse, converged).

study

The original irt_study object.

iterations

Number of replications run.

seed

Base seed used.

elapsed

Elapsed wall-clock time in seconds.

se

Logical flag indicating whether SEs and CIs were computed.

compute_theta

Logical flag indicating whether theta recovery metrics were computed.

See Also

irt_study() for specifying study conditions, summary.irt_results() and plot.irt_results() for analyzing output, irt_iterations() for determining the number of replications.

Examples

# Minimal example (iterations and sample sizes reduced for speed;
# use iterations >= 100 and 3+ sample sizes in practice)
design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)
summary(results)
plot(results)

Description

Add study-level conditions to an IRT design specification. This captures decisions 4–5 from the Schroeders & Gnambs (2025) framework: sample sizes and missing data mechanism.

Usage

irt_study(
  design,
  sample_sizes,
  missing = "none",
  missing_rate = NULL,
  test_design = NULL,
  estimation_model = NULL
)

Arguments

Value

An S3 object of class irt_study (a named list) with elements design, missing, missing_rate, sample_sizes, test_design, and estimation_model.

See Also

irt_design() for the design specification, irt_simulate() to run the simulation.

Examples

# Simple study with no missing data
d <- irt_design(
  model = "1PL", n_items = 20,
  item_params = list(b = seq(-2, 2, length.out = 20))
)
study <- irt_study(d, sample_sizes = c(100, 250, 500))

# Study with MCAR missingness
study_mcar <- irt_study(d, sample_sizes = c(200, 400),
                        missing = "mcar", missing_rate = 0.2)

# Model misspecification: generate 2PL, fit 1PL
d_2pl <- irt_design(
  model = "2PL", n_items = 15,
  item_params = list(a = rlnorm(15, 0, 0.25), b = rnorm(15))
)
study_misspec <- irt_study(d_2pl, sample_sizes = c(100, 300),
                           estimation_model = "1PL")

Description

Visualize performance criteria across sample sizes from an irt_simulate() result. Calls summary.irt_results() internally, then plots the requested criterion by sample size.

Usage

## S3 method for class 'irt_results'
plot(x, criterion = "rmse", param = NULL, item = NULL, threshold = NULL, ...)

Arguments

Value

A ggplot2::ggplot object, returned invisibly.

See Also

summary.irt_results() for the underlying criteria, recommended_n() for sample-size recommendations.

Examples

design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)
plot(results)
plot(results, criterion = "bias", threshold = 0.05, param = "b")

Description

Visualize performance criteria from a summary.irt_results() object. This is a convenience method for users who already have a summary; plot.irt_results() is the primary interface.

Usage

## S3 method for class 'summary_irt_results'
plot(x, criterion = "rmse", param = NULL, item = NULL, threshold = NULL, ...)

Arguments

Value

A ggplot2::ggplot object, returned invisibly.

See Also

plot.irt_results(), summary.irt_results()

Examples

design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)
s <- summary(results)
plot(s, criterion = "rmse", threshold = 0.15)

Description

Display a compact summary of an irt_design object, including model type, number of items, theta distribution, and parameter ranges.

Usage

## S3 method for class 'irt_design'
print(x, ...)

Arguments

Value

x, invisibly.

See Also

irt_design()

Examples

d <- irt_design("1PL", 10, list(b = seq(-2, 2, length.out = 10)))
print(d)

Description

Display a compact summary of an irt_simulate() result, including model, items, sample sizes, iterations, convergence rate, and elapsed time.

Usage

## S3 method for class 'irt_results'
print(x, ...)

Arguments

Value

x, invisibly.

See Also

irt_simulate()

Examples

design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)
print(results)

Description

Display a compact summary of an irt_study object, including model, items, sample sizes, and missing data mechanism.

Usage

## S3 method for class 'irt_study'
print(x, ...)

Arguments

Value

x, invisibly.

See Also

irt_study()

Examples

d <- irt_design("1PL", 10, list(b = seq(-2, 2, length.out = 10)))
s <- irt_study(d, sample_sizes = c(100, 500))
print(s)

Description

Display item parameter criteria and theta recovery statistics from a summary.irt_results() object.

Usage

## S3 method for class 'summary_irt_results'
print(x, ...)

Arguments

Value

x, invisibly.

See Also

summary.irt_results()

Examples

design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)
s <- summary(results)
print(s)

Description

Given a summary.irt_results() object, find the smallest sample size at which a performance criterion meets the specified threshold for each item and parameter combination.

Usage

recommended_n(object, ...)

## S3 method for class 'summary_irt_results'
recommended_n(
  object,
  criterion,
  threshold,
  param = NULL,
  item = NULL,
  aggregate = c("max", "mean", "median", "none"),
  ...
)

Arguments

Details

For criteria where smaller is better (bias, empirical_se, mse, rmse, mcse_bias, mcse_mse), the threshold is met when the criterion value is at or below the threshold. For bias, the absolute value is used. For coverage (where higher is better), the threshold is met when coverage is at or above the threshold.

Value

When aggregate = "none", a data frame with columns:

item

Item number.

param

Parameter name.

recommended_n

Minimum sample size meeting the threshold, or NA if no tested sample size meets it.

criterion

The criterion used (echoed back for reference).

threshold

The threshold used (echoed back for reference).

When aggregate is "max", "mean", or "median" (the typical case), an integer scalar carrying the recommended sample size with attributes details (the per-item data frame above), aggregate, criterion, and threshold. If any item/param combination fails to meet the threshold at every tested sample size, the aggregate is NA_integer_ and a warning lists the affected combinations.

See Also

summary.irt_results() for computing criteria, plot.irt_results() for visualization.

Examples

design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)
s <- summary(results)

# Default — single recommended N (max across items) for RMSE <= 0.20
n_rec <- recommended_n(s, criterion = "rmse", threshold = 0.20)
n_rec
attr(n_rec, "details")  # per-item breakdown

# Mean / median aggregates (rounded up via ceiling)
recommended_n(s, criterion = "rmse", threshold = 0.20, aggregate = "mean")

# Legacy behavior — full per-item data frame
recommended_n(s, criterion = "rmse", threshold = 0.20, aggregate = "none")

# Minimum N for 95% coverage on difficulty parameters only
recommended_n(s, criterion = "coverage", threshold = 0.95, param = "b")

Description

Compute performance criteria for each sample size, item, and parameter combination from an irt_simulate() result. Criteria follow Morris et al. (2019) definitions. Optionally, users can provide a custom callback function to compute additional item-level performance criteria (e.g., conditional reliability, external criterion SE).

Usage

## S3 method for class 'irt_results'
summary(object, criterion = NULL, param = NULL, criterion_fn = NULL, ...)

Arguments

Value

An S3 object of class summary_irt_results containing:

item_summary

Data frame with one row per sample_size × item × param combination, containing the requested criteria plus n_converged and any custom columns from criterion_fn.

theta_summary

Data frame with one row per sample_size, containing mean_cor, sd_cor, mean_rmse, sd_rmse, and n_converged.

iterations

Number of replications.

seed

Base seed used.

model

IRT model type.

References

Morris, T. P., White, I. R., & Crowther, M. J. (2019). Using simulation studies to evaluate statistical methods. Statistics in Medicine, 38(11), 2074–2102. doi:10.1002/sim.8086

See Also

irt_simulate() for running simulations, plot.irt_results() for visualization, recommended_n() for sample-size recommendations.

Examples

# Minimal example (iterations reduced for speed; use 100+ in practice)
design <- irt_design(
  model = "1PL", n_items = 5,
  item_params = list(b = seq(-2, 2, length.out = 5))
)
study <- irt_study(design, sample_sizes = c(200, 500))
results <- irt_simulate(study, iterations = 10, seed = 42)

s <- summary(results)
s$item_summary
s$theta_summary

# Only bias and RMSE for difficulty parameters
summary(results, criterion = c("bias", "rmse"), param = "b")

# Compute custom criterion: relative bias
custom_fn <- function(estimates, true_value, ci_lower, ci_upper, converged, ...) {
  valid_est <- estimates[!is.na(estimates)]
  rel_bias <- (mean(valid_est) - true_value) / true_value
  c(relative_bias = rel_bias)
}
summary(results, criterion_fn = custom_fn)

# Multiple custom criteria
multi_fn <- function(estimates, true_value, ci_lower, ci_upper, converged, ...) {
  valid_est <- estimates[!is.na(estimates)]
  c(mean_est = mean(valid_est), sd_est = sd(valid_est))
}
summary(results, criterion_fn = multi_fn)