build_mfrm_sim_spec: Build an explicit simulation specification for MFRM design...

In mfrmr: Estimation and Diagnostics for Many-Facet Measurement Models

Build an explicit simulation specification for MFRM design studies

Description

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.

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.

Value

An object of class mfrm_sim_spec.

Interpreting output

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

See Also

extract_mfrm_sim_spec(), simulate_mfrm_data()

Examples

spec <- build_mfrm_sim_spec(
  n_person = 30,
  n_rater = 4,
  n_criterion = 3,
  raters_per_person = 2,
  assignment = "rotating"
)
spec$model
spec$assignment
spec$threshold_table

mfrmr documentation built on March 31, 2026, 1:06 a.m.