Saqrlab ships two curated reference datasets — LEARNING_STATES (learning-action verbs across 8 categories) and GLOBAL_NAMES (culturally diverse names by region) — plus accessor and selection helpers that turn them into ready-to-use state labels and node names. A small validation utility, validate_sim_params(), standardizes simulation parameter lists.

LEARNING_STATES

A named list of learning-action verbs organized into 8 categories drawn from the learning-sciences literature.

Structure

length(LEARNING_STATES)
#> [1] 8
names(LEARNING_STATES)
#> [1] "metacognitive"    "cognitive"        "behavioral"       "social"          
#> [5] "motivational"     "affective"        "group_regulation" "lms"
lengths(LEARNING_STATES)
#>    metacognitive        cognitive       behavioral           social 
#>               20               30               30               30 
#>     motivational        affective group_regulation              lms 
#>               30               30                9               30
lapply(LEARNING_STATES, head, 5)
#> $metacognitive
#> [1] "Plan"     "Monitor"  "Evaluate" "Reflect"  "Regulate"
#> 
#> $cognitive
#> [1] "Read"      "Study"     "Analyze"   "Summarize" "Memorize" 
#> 
#> $behavioral
#> [1] "Practice" "Annotate" "Research" "Review"   "Revise"  
#> 
#> $social
#> [1] "Collaborate" "Discuss"     "Seek_help"   "Question"    "Explain"    
#> 
#> $motivational
#> [1] "Focus"   "Persist" "Explore" "Create"  "Strive" 
#> 
#> $affective
#> [1] "Enjoy"      "Appreciate" "Value"      "Interest"   "Curious"   
#> 
#> $group_regulation
#> [1] "Adapt"      "Cohesion"   "Consensus"  "Coregulate" "Discuss"   
#> 
#> $lms
#> [1] "View"     "Access"   "Download" "Upload"   "Submit"

GROUP_REGULATION_ACTIONS

A character vector of socially-shared regulation of learning (SSRL) action verbs, convenient as a ready-made state set for group-regulation simulations.

Structure

length(GROUP_REGULATION_ACTIONS)
#> [1] 9
GROUP_REGULATION_ACTIONS
#> [1] "adapt"      "cohesion"   "consensus"  "coregulate" "discuss"   
#> [6] "emotion"    "monitor"    "plan"       "synthesis"

GLOBAL_NAMES

A named list of ~1000 culturally diverse first names, grouped by world region, for naming actors/nodes in simulations.

Structure

length(GLOBAL_NAMES)
#> [1] 25
head(names(GLOBAL_NAMES), 10)
#>  [1] "western_europe"  "eastern_europe"  "southern_europe" "nordic"         
#>  [5] "arab"            "persian"         "turkish"         "central_asia"   
#>  [9] "south_asia"      "east_asia"
lapply(GLOBAL_NAMES[c("western_europe", "arab", "east_asia")], head, 5)
#> $western_europe
#> [1] "Emma"  "Liam"  "Chloe" "Jack"  "Lily" 
#> 
#> $arab
#> [1] "Ali"    "Fatima" "Omar"   "Layla"  "Yusuf" 
#> 
#> $east_asia
#> [1] "Wei"  "Lin"  "Chen" "Mei"  "Jing"

get_learning_states()

Retrieve learning verbs by category, optionally taking a random sample and combining several categories.

Signature

args(get_learning_states)
#> function (categories = "all", n = NULL, seed = NULL) 
#> NULL

Example

# All category names
names(get_learning_states())
#> NULL

# Cognitive verbs only
head(get_learning_states("cognitive"))
#> [1] "Read"      "Study"     "Analyze"   "Summarize" "Memorize"  "Connect"

# Random 6 verbs across two categories (seeded)
get_learning_states(c("social", "cognitive"), n = 6, seed = 1)
#> [1] "Categorize"  "Question"    "Synthesize"  "Collaborate" "Summarize"  
#> [6] "Listen"

select_states() / smart_select_states()

Intelligently select a set of n_states labels, balancing a primary and secondary category by primary_ratio. smart_select_states() is an alias for select_states().

Signature

args(select_states)
#> function (n_states, primary_categories = NULL, secondary_categories = NULL, 
#>     primary_ratio = 0.6, seed = NULL) 
#> NULL
args(smart_select_states)
#> function (...) 
#> NULL

Example

# Auto-strategy: number of categories scales with n_states
select_states(8, seed = 42)
#> [1] "Submit"    "Synthesis" "Sustain"   "Plan"      "Forecast"  "Strive"   
#> [7] "Judge"     "Cohesion"

# Explicit primary category
smart_select_states(5, primary_categories = "metacognitive", seed = 1)
#> [1] "Adapt"   "Plan"    "Upload"  "Reflect" "Scan"

list_learning_categories()

Return a tidy data frame summarizing each learning-state category with its verb count and example verbs.

Signature

args(list_learning_categories)
#> function () 
#> NULL

Example

list_learning_categories()

get_global_names()

Retrieve diverse first names, optionally sampling n of them and restricting to one or more regions.

Signature

args(get_global_names)
#> function (n = NULL, regions = "all", seed = NULL) 
#> NULL

Example

# 8 names from the Arab region (seeded)
get_global_names(n = 8, regions = "arab", seed = 1)
#> [1] "Jamal" "Layla" "Tarek" "Ali"   "Mona"  "Faris" "Amr"   "Moza"

# Sample across all regions
get_global_names(n = 6, seed = 1)
#> [1] "Martin"   "Ayu"      "Lucia"    "Claudine" "Vikram"   "Nada"

list_name_regions()

Return a tidy data frame summarizing each name region with its count and example names.

Signature

args(list_name_regions)
#> function () 
#> NULL

Example

head(list_name_regions())
#> Available region shortcuts:
#>   europe, middle_east, asia, africa, americas, oceania
#>   western, eastern, mediterranean, sub_saharan, pacific, indigenous

validate_sim_params()

Validate and standardize a list of simulation parameters, applying defaults and enforcing relationships (e.g. min_na <= max_na <= seq_length). Both new and legacy parameter names are accepted.

Signature

args(validate_sim_params)
#> function (params) 
#> NULL

Example — valid call

validate_sim_params(list(
  seq_length  = 50,
  n_sequences = 200,
  min_na      = 2,
  max_na      = 10
))
#> $seq_length
#> [1] 50
#> 
#> $n_sequences
#> [1] 200
#> 
#> $min_na
#> [1] 2
#> 
#> $max_na
#> [1] 10
#> 
#> $max_seq_length
#> [1] 50
#> 
#> $num_rows
#> [1] 200

Example — invalid call (wrapped in try() so the doc still renders)

try(validate_sim_params("not_a_list"))
#> Error in params$max_seq_length : $ operator is invalid for atomic vectors