Build an explicit simulation specification for MFRM design studies

Usage

build_mfrm_sim_spec(
  n_person = 50,
  n_rater = 4,
  n_criterion = 4,
  raters_per_person = n_rater,
  score_levels = 4,
  theta_sd = 1,
  rater_sd = 0.35,
  criterion_sd = 0.25,
  noise_sd = 0,
  step_span = 1.4,
  thresholds = NULL,
  model = c("RSM", "PCM"),
  step_facet = "Criterion",
  assignment = c("crossed", "rotating", "resampled", "skeleton"),
  latent_distribution = c("normal", "empirical"),
  empirical_person = NULL,
  empirical_rater = NULL,
  empirical_criterion = NULL,
  assignment_profiles = NULL,
  design_skeleton = NULL,
  group_levels = NULL,
  dif_effects = NULL,
  interaction_effects = NULL
)

Arguments

n_person: Number of persons/respondents to generate.
n_rater: Number of rater facet levels to generate.
n_criterion: Number of criterion/item facet levels to generate.
raters_per_person: Number of raters assigned to each person.
score_levels: Number of ordered score categories.
theta_sd: Standard deviation of simulated person measures.
rater_sd: Standard deviation of simulated rater severities.
criterion_sd: Standard deviation of simulated criterion difficulties.
noise_sd: Optional observation-level noise added to the linear predictor.
step_span: Spread used to generate equally spaced thresholds when thresholds = NULL.
thresholds: Optional threshold specification. Use either a numeric vector of common thresholds or a data frame with columns StepFacet, Step/StepIndex, and Estimate.
model: Measurement model recorded in the simulation specification.
step_facet: Step facet used when model = "PCM" and threshold values vary across levels.
assignment: Assignment design. "crossed" means every person sees every rater; "rotating" uses a balanced rotating subset; "resampled" reuses empirical person-level rater-assignment profiles; "skeleton" reuses an observed person-by-facet design skeleton.
latent_distribution: Latent-value generator. "normal" samples from centered normal distributions using the supplied standard deviations. "empirical" resamples centered support values from empirical_person/empirical_rater/empirical_criterion.
empirical_person: Optional numeric support values used when latent_distribution = "empirical".
empirical_rater: Optional numeric support values used when latent_distribution = "empirical".
empirical_criterion: Optional numeric support values used when latent_distribution = "empirical".
assignment_profiles: Optional data frame with columns TemplatePerson and Rater (optionally Group) describing empirical person-level rater-assignment profiles used when assignment = "resampled".
design_skeleton: Optional data frame with columns TemplatePerson, Rater, and Criterion (optionally Group and Weight) describing an observed response skeleton used when assignment = "skeleton".
group_levels: Optional character vector of group labels.
dif_effects: Optional data frame of true group-linked DIF effects.
interaction_effects: Optional data frame of true interaction effects.

Value

An object of class mfrm_sim_spec.

Details

build_mfrm_sim_spec() creates an explicit, portable simulation specification that can be passed to simulate_mfrm_data(). The goal is to make the data-generating mechanism inspectable and reusable rather than relying only on ad hoc scalar arguments.

The resulting object records:

design counts (n_person, n_rater, n_criterion, raters_per_person)
latent spread assumptions (theta_sd, rater_sd, criterion_sd)
optional empirical latent support values for semi-parametric simulation
threshold structure (threshold_table)
assignment design (assignment)
optional empirical assignment profiles (assignment_profiles) with optional person-level Group labels
optional observed response skeleton (design_skeleton) with optional person-level Group labels and observation-level Weight values
optional signal tables for DIF and interaction bias

The current generator still targets the package's standard person x rater x criterion workflow. When threshold values are provided by StepFacet, the supported step facets are the generated Rater or Criterion levels.

Interpreting output

This object does not contain simulated data. It is a data-generating specification that tells simulate_mfrm_data() how to generate them.

Examples

spec <- build_mfrm_sim_spec(
  n_person = 30,
  n_rater = 4,
  n_criterion = 3,
  raters_per_person = 2,
  assignment = "rotating"
)
spec$model
#> [1] "RSM"
spec$assignment
#> [1] "rotating"
spec$threshold_table
#> # A tibble: 3 × 4
#>   StepFacet StepIndex Step   Estimate
#>   <chr>         <int> <chr>     <dbl>
#> 1 Common            1 Step_1     -1.4
#> 2 Common            2 Step_2      0  
#> 3 Common            3 Step_3      1.4