This page documents Saqrlab’s “laboratory” layer — the unified front door to the simulators. simulate() dispatches to any registered simulator by name and returns a tidy saqr_sim object; validate_recovery() checks how well an estimator recovers known ground-truth parameters; and the scenario system (list_scenarios() / get_scenario() / run_scenario()) packages named, multi-case experiments that can be tidied and exported to disk.

saqr_sim()

Constructs the standard saqr_sim result object that wraps a simulated data frame together with its ground-truth params, the simulator type, and the seed. Every explicit-parameter simulator returns one of these.

Signature

args(saqr_sim)
#> function (data, params, type, seed = NULL, call = NULL, extras = list()) 
#> NULL

Example

sim <- saqr_sim(
  data = data.frame(x = rnorm(10), y = rnorm(10)),
  params = list(mean_x = 0, mean_y = 0),
  type = "demo", seed = 1
)
sim
#> saqr_sim [demo]  10 x 2  (seed=1)
#>   params: mean_x, mean_y 
#>   cols:   x, y

The class carries a full set of S3 methods so it behaves like a tidy result:

class(sim)
#> [1] "saqr_sim" "list"
names(sim)             # data, params
#> [1] "data"   "params" "type"   "seed"   "call"
dim(sim)               # dims of the underlying data frame
#> [1] 10  2
head(sim)              # head of $data
summary(sim)           # data summary + parameter list
#> Simulation type: demo
#> Seed: 1
#> 
#> --- Data ---
#>        x                 y           
#>  Min.   :-0.8356   Min.   :-2.21470  
#>  1st Qu.:-0.5462   1st Qu.:-0.03775  
#>  Median : 0.2566   Median : 0.49187  
#>  Mean   : 0.1322   Mean   : 0.24884  
#>  3rd Qu.: 0.5537   3rd Qu.: 0.91318  
#>  Max.   : 1.5953   Max.   : 1.51178  
#> 
#> --- Parameters ---
#> List of 2
#>  $ mean_x: num 0
#>  $ mean_y: num 0
sim$data |> head(3)    # the simulated data frame
sim$params             # the ground-truth parameters
#> $mean_x
#> [1] 0
#> 
#> $mean_y
#> [1] 0
as.data.frame(sim) |> head(3)  # tidy accessor -> the data frame

simulate()

The universal dispatcher: simulate(type, ...) routes to the named simulator with explicit named arguments and returns a saqr_sim. The seed argument makes any draw reproducible.

Signature

args(simulate)
#> function (type, ..., seed = NULL) 
#> NULL

Example

ttest_sim <- simulate("ttest", n_a = 50, n_b = 50,
                      mean_a = 0, mean_b = 0.5, seed = 1)
ttest_sim
#> saqr_sim [ttest]  100 x 2  (seed=1)
#>   params: mean_a, mean_b, sd_a, sd_b, n_a, n_b, cohens_d 
#>   cols:   group, score
head(ttest_sim)

list_simulators()

Returns the catalogue of registered simulator names with their descriptions as a tidy data.frame.

Signature

args(list_simulators)
#> function () 
#> NULL

Example

list_simulators()

validate_recovery()

Compares a vector of estimated parameters against the ground-truth params stored in a saqr_sim, returning a recovery_result table of absolute and relative error with a within-tolerance flag per parameter.

Signature

args(validate_recovery)
#> function (sim, estimates, params = NULL, tolerance = 0.1, relative = TRUE) 
#> NULL

Example

End-to-end: simulate a regression with known coefficients, fit it with lm(), and feed the fitted coefficients back in as estimates. The estimate names must match the coefs.* parameter names stored by simulate_regression().

rsim <- simulate_regression(
  coefs = c("(Intercept)" = 1, x1 = 2, x2 = -1.5),
  predictor_sds = c(x1 = 1, x2 = 1),
  error_sd = 1, n = 2000, seed = 7
)
names(rsim$params)   # confirm the coefs.* parameter names
#> [1] "coefs"         "predictor_sds" "error_sd"

fit_lm <- lm(y ~ x1 + x2, data = rsim$data)
est <- stats::setNames(coef(fit_lm), paste0("coefs.", names(coef(fit_lm))))

recovery <- validate_recovery(rsim, estimates = est)
recovery
summary(recovery)

list_scenarios()

Lists the built-in named scenarios — pre-packaged, multi-case experiments — as a tidy data.frame.

Signature

args(list_scenarios)
#> function () 
#> NULL

Example

list_scenarios()

get_scenario()

Returns the parameter specification(s) for a named scenario: the full list of cases, or a single case when case is supplied.

Signature

args(get_scenario)
#> function (scenario, case = NULL) 
#> NULL

Example

power_spec <- get_scenario("power_ttest")
length(power_spec)        # one entry per case
#> [1] 6
power_spec[[1]]           # the first case's parameters
#> $n_a
#> [1] 30
#> 
#> $n_b
#> [1] 30
#> 
#> $mean_a
#> [1] 0
#> 
#> $mean_b
#> [1] 0.2

get_scenario("power_ttest", case = 1)
#> $n_a
#> [1] 30
#> 
#> $n_b
#> [1] 30
#> 
#> $mean_a
#> [1] 0
#> 
#> $mean_b
#> [1] 0.2

run_scenario()

Executes every case of a named scenario with a single seed, returning a list of per-case saqr_sim results.

Signature

args(run_scenario)
#> function (scenario, seed = NULL) 
#> NULL

Example

scenario_run <- run_scenario("power_ttest", seed = 1)
names(scenario_run)       # one element per case
#> [1] "case1" "case2" "case3" "case4" "case5" "case6"
scenario_run[[1]]
#> saqr_sim [ttest]  60 x 2  (seed=2)
#>   params: mean_a, mean_b, sd_a, sd_b, n_a, n_b, cohens_d 
#>   cols:   group, score

tidy_simulation_results()

Flattens a run_scenario() result into a single tidy data.frame, stacking the cases with a .case column and joining in each case’s parameters.

Signature

args(tidy_simulation_results)
#> function (x) 
#> NULL

Example

tidy <- tidy_simulation_results(scenario_run)
head(tidy)

export_simulation()

Writes a scenario run (or its tidied form) to a CSV file on disk, returning the path invisibly.

Signature

args(export_simulation)
#> function (x, file) 
#> NULL

Example

out_path <- tempfile(fileext = ".csv")
export_simulation(tidy, out_path)
file.exists(out_path)
#> [1] TRUE
head(read.csv(out_path))