Skip to contents

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, and SE. 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_names

  • Provide 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"