This function generates simulated item difficulties by drawing from normal distributions centered around existing difficulty estimates and their associated standard errors. The result is a mixture distribution, from which new difficulties are sampled using inverse CDF sampling.
Usage
irw_simu_diff(
num_items = 10,
num_replications = 1,
irw_names = NULL,
difficulty_pool = NULL
)Arguments
- num_items
Number of item difficulties to simulate per replication.
- num_replications
Number of replications to perform. If 1, returns a numeric vector. If >1, returns a data frame.
- irw_names
Optional character vector of IRW dataset names to filter from
diff_long.- difficulty_pool
Optional custom data frame with columns
dataset,difficulty, andSE. If provided, overrides the default IRW difficulty pool (diff_long).
Value
A numeric vector of difficulties (if num_replications = 1), or a data frame
with replication and difficulty columns (if num_replications > 1).
Details
By default, the function uses diff_long, a built-in dataset included in the irw package.
This dataset contains item difficulty estimates and standard errors from a curated
subset of IRW datasets. You can:
Use the full IRW difficulty pool (
diff_long)Filter to specific IRW datasets via
irw_namesProvide your own difficulty pool via
difficulty_pool
This method is based on Zhang et al. (2025), which constructs realistic empirical distributions by accounting for uncertainty around item difficulty estimates.
References
Zhang, L., Liu, Y., Molenaar, D., & Domingue, B. (2025). Realistic Simulation of Item Difficulties. https://doi.org/10.31234/osf.io/jbhxy_v1
Examples
# Use all IRW data (default)
irw_simu_diff(num_items = 5)
#> [1] 0.8701744 1.4163690 1.2278023 -0.0206545 0.1909236
# Filter to specific IRW datasets
irw_simu_diff(num_items = 5, irw_names = c("psychtools_epi", "psychtools_blot"))
#> [1] -1.8006003 3.4503334 0.6773411 1.6305682 -0.1590296
# Use a custom difficulty pool
my_pool <- data.frame(dataset = "x",
difficulty = c(-0.2, 0.1),
SE = c(0.1, 0.2))
irw_simu_diff(num_items = 5, difficulty_pool = my_pool)
#> [1] -0.2409751 -0.1730095 -0.1372999 0.0691039 -0.0887331
# Explore built-in IRW difficulty pool
head(diff_long)
#> # A tibble: 6 × 4
#> dataset item difficulty SE
#> <chr> <chr> <dbl> <dbl>
#> 1 ALSECYPIAMH_WU_2022_NEI X1 0.213 0.0517
#> 2 ALSECYPIAMH_WU_2022_NEI X2 -0.325 0.0475
#> 3 ALSECYPIAMH_WU_2022_NEI X3 0.275 0.0524
#> 4 ALSECYPIAMH_WU_2022_NEI X4 -0.539 0.0470
#> 5 ALSECYPIAMH_WU_2022_NEI X5 0.376 0.0537
#> 6 ALSECYPIAMH_WU_2022_PEI X1 0.648 0.0430
unique(diff_long$dataset)
#> [1] "ALSECYPIAMH_WU_2022_NEI"
#> [2] "ALSECYPIAMH_WU_2022_PEI"
#> [3] "art"
#> [4] "artistic_preferences"
#> [5] "BAFACALO_Golino_2013_BVPS"
#> [6] "BAFACALO_Golino_2013_SMS"
#> [7] "borges_brazil_residency_2024_cbt"
#> [8] "borges_brazil_residency_2024_pbt"
#> [9] "chile_2023_children-adolescents-survey_cp_c"
#> [10] "csft_ye_2025"
#> [11] "difnlr_msatb"
#> [12] "dscore_macarthur_weber_2019"
#> [13] "EEN_Lacey_2024_Parent"
#> [14] "erf_breuer_2017_frmmc"
#> [15] "experimental_iq"
#> [16] "face_memory_test"
#> [17] "fisher_temperment"
#> [18] "florida_twins_dbi"
#> [19] "florida_twins_media"
#> [20] "gcbs_brotherton_2013_vcl"
#> [21] "gilbert_meta_100"
#> [22] "gilbert_meta_102"
#> [23] "gilbert_meta_103"
#> [24] "gilbert_meta_104"
#> [25] "gilbert_meta_55"
#> [26] "gilbert_meta_90"
#> [27] "idcr_martinez_2023_analogies"
#> [28] "idcr_martinez_2023_info"
#> [29] "idcr_martinez_2023_numSeries"
#> [30] "idcr_martinez_2023_ps"
#> [31] "idcr_martinez_2023_raco"
#> [32] "idcr_martinez_2023_ravens"
#> [33] "idcr_martinez_2023_Story_Recall_2"
#> [34] "idcr_martinez_2023_Story_Recall_3"
#> [35] "idcr_martinez_2023_vocab"
#> [36] "lec5_xiong_2025"
#> [37] "lys_2020_rape_3_sds"
#> [38] "MGSISGCLQ_Hollyhead_2018"
#> [39] "much_tte_2025_actionorientation"
#> [40] "much_tte_2025_concentrationtask"
#> [41] "much_tte_2025_matrixreasoning"
#> [42] "nature_relatedness"
#> [43] "nerdy_personality"
#> [44] "neurodegenerative_huizinga_2019_sims"
#> [45] "nomt_hooper_2024_study1"
#> [46] "nomt_hooper_2024_study2"
#> [47] "paampsmartsud_saba_2023_attendance"
#> [48] "pechorro_impulsivity_2021_rpq"
#> [49] "pinheiro_2023_srq"
#> [50] "pks_probability"
#> [51] "PPSRS_Caliciuri_2024"
#> [52] "preschool_sel_akt"
#> [53] "preschool_sel_box"
#> [54] "preschool_sel_dn"
#> [55] "preschool_sel_htks"
#> [56] "project_kids_told_grade"
#> [57] "project_kids_topel"
#> [58] "protestant_workethic"
#> [59] "psychoneurotic_inventory"
#> [60] "PTAM_Kretzschmar_2017_Reasoning"
#> [61] "rdatasets_gssabortion"
#> [62] "rightwing_authoritariansim"
#> [63] "roar_gijbels2024"
#> [64] "spelling_assessment_study1"
#> [65] "spelling_assessment_study2"
#> [66] "SPQVS_Barnby_2017_OLIFE"
#> [67] "timss_tam"
#> [68] "tma"
#> [69] "Veterans_Affairs_SSVF_Survey_2018-20"
#> [70] "vocabulary_iq"
#> [71] "wang_onlineriskexp_2025_interpersonalsecurity"
#> [72] "wooly_hartman2022"
#> [73] "4thgrade_math_sirt"
#> [74] "alcoholresearch_sumscore"
#> [75] "balance_mokken"
#> [76] "big5_sirt"
#> [77] "cdm_ecpe"
#> [78] "cdm_hr"
#> [79] "cdm_pisa00R"
#> [80] "cdm_timss03"
#> [81] "cdm_timss07"
#> [82] "chess_lnirt"
#> [83] "CPDMMC_Kunnari_2020_PDP"
#> [84] "criticalperiod_syntax"
#> [85] "DART_Brysbaert_2020_1"
#> [86] "dd_rotation"
#> [87] "difNLR_msatb"
#> [88] "EEN_Lacey_2024_Children"
#> [89] "FACIT_YOUNT_2021_clinic10"
#> [90] "fictionexposure_wimmer"
#> [91] "fims_tam"
#> [92] "frac20"
#> [93] "g308_sirt"
#> [94] "GART_Grolig_2020"
#> [95] "geiser_tam"
#> [96] "gilbert_meta_1"
#> [97] "gilbert_meta_11"
#> [98] "gilbert_meta_12"
#> [99] "gilbert_meta_15"
#> [100] "gilbert_meta_16"
#> [101] "gilbert_meta_2"
#> [102] "gilbert_meta_37"
#> [103] "gilbert_meta_38"
#> [104] "gilbert_meta_39"
#> [105] "gilbert_meta_40"
#> [106] "gilbert_meta_7"
#> [107] "gilbert_meta_8"
#> [108] "janssen2_tam"
#> [109] "kfcovid_Li2020"
#> [110] "lsat"
#> [111] "mcmi_mokken"
#> [112] "mental_health_malawi"
#> [113] "mobility"
#> [114] "mpsycho_Rmotivation"
#> [115] "mpsycho_rwdq"
#> [116] "mpsycho_wilmer"
#> [117] "mpsycho_zareki"
#> [118] "naep_multilcirt"
#> [119] "NAMPRB_Siwiak_2024_KON2066"
#> [120] "novelobjectmatching"
#> [121] "orev_bohn2024"
#> [122] "pirlsmissing_sirt"
#> [123] "pisa2003_problem_solving"
#> [124] "pisa2003_science"
#> [125] "PMT_Trzcinska_2023_finans"
#> [126] "PMT_Trzcinska_2023_PMT"
#> [127] "polca_carcinoma"
#> [128] "preschool_sel"
#> [129] "previc_bohn2023"
#> [130] "promis1wave1_physicalfunction"
#> [131] "psychtools_ability"
#> [132] "psychtools_blot"
#> [133] "psychtools_epi"
#> [134] "PTAM_Kretzschmar_2017_Raven"
#> [135] "quantshort"
#> [136] "RDatasets_gssabortion"
#> [137] "roar_lexical"
#> [138] "spidersBAT_grill2024"
#> [139] "tdri"
#> [140] "test_taking_patterns_over_time"
#> [141] "transreas_mokken"
#> [142] "trees_sirt"
#> [143] "verbagg"
#> [144] "vocab_assessment_3_to_8_year_old_children"
#> [145] "wirs"