Generates multiple scenarios with identical model structure (model, RUV, RE, OCC, COVS) and different sampled initial values for population parameters.
For each start, initial values of estimated parameters are sampled
uniformly within specified intervals, and a corresponding .mlxtran file
is generated. A summary table describing all multistart scenarios is written
to disk.
Usage
sg_multistart(
mod,
data,
headers,
ruv,
theta,
re,
occ,
path,
covs_lst = NULL,
opt_name = "Simurg",
project_name = "multistart_project",
n_starts = 10,
theta_intervals = NULL,
interval_factor = c(0.2, 5),
vary_params = NULL,
seed = NULL
)Arguments
- mod
Model file path or model identifier used for scenario generation.
- data
Character string. Path to the dataset used in model fitting or simulation.
- headers
Predefined list of dataset column names (e.g., ID, TIME, DV, etc.) used by the modeling framework.
- ruv
Residual unexplained variability (RUV) structure. Each element contains RUV properties (e.g.,
YNAME,ERR) and mapping to data.- theta
Tibble describing population parameter properties. Tibble should contain columns such as
NAME,INIT, andEST.- re
Random effects (RE) specification. Includes matrices
initandestdefining initial and estimated covariance structures.- occ
Occasion effect matrices. Includes
initandestmatrices defining inter-occasion variability.- path
Character. Directory path where output files (CSV summary and model files) will be written. Default is current working directory.
- covs_lst
Optional list describing covariate-parameter relationships. Each element should include fields such as
PAR,COVNAME, andESTindicating inclusion in the model.- opt_name
Character. Optimization engine name (e.g.,
"Monolix","Simurg"). Default"Simurg".- project_name
Character. Base name for the exported project files. Default
"my_project".- n_starts
Number of multistart runs (number of initial value scenarios).
- theta_intervals
Optional data frame specifying sampling intervals for initial values. Must contain columns
NAME,lower, andupper. IfNULL, intervals are derived frominterval_factor.- interval_factor
Numeric vector of length 2 specifying multiplicative lower and upper bounds factors relative to original
INITvalues (defaultc(0.2, 5)).- vary_params
List of parameters which inital values are varied. Default value implies all parameters are varied. If
theta_intervalis specified, list of parameters is taken fromtheta_interval- seed
Optional random seed for reproducible sampling of initial values. If
NULL, the global RNG state is not modified.
Value
The function writes two types of outputs to the specified path:
A CSV file (
scenarios_info.csv) summarizing all generated scenarios with columns:- scenario_number
Unique index of the scenario.
- model
Model file or path used in the scenario.
- data
Path to the dataset used.
- theta
Active population parameters and initial values used.
- RUV
Residual error structure(s) used.
- RE
Random effect and correlation terms included.
- OCC
Active occasion effects.
- COVS
Included covariate-parameter relationships.
Individual
.mlxtranmodel files for each generated scenario, named according to the pattern<project_name>_<i>.mlxtran.
Details
For each start:
Population parameter initial values
INITfor estimated parameters are sampled uniformly.A scenario summary is stored.
The corresponding
.mlxtranproject files are written.
If seed is provided, the function temporarily sets the
random number generator state and restores it upon exit.
Examples
# \donttest{
library(dplyr)
folder_path <- system.file("extdata", package = "SimuRg")
#> Warning: cannot open compressed file '/tmp/RtmpLedq7K/temp_libpath8b6abff614d/SimuRg/DESCRIPTION', probable reason 'No such file or directory'
mod <- paste(folder_path, "/models/model_PK_1c.txt", sep = "/")
data <- paste(folder_path, "datasets", "dspk-warf.csv", sep = "/")
re <- list(init = tribble(~Cl, ~Vd, ~ka, ~Vp, ~Q,
1, 0, 0, 0, 0,
0, 1, 0, 0, 0,
0, 0, 1, 0, 0,
0, 0, 0, 1, 0,
0, 0, 0, 0, 1) %>% as.matrix(),
est = tribble(~Cl, ~Vd, ~ka, ~Vp, ~Q,
TRUE, NA, NA, NA, NA,
NA, TRUE, NA, NA, NA,
NA, NA, TRUE, NA, NA,
NA, NA, NA, TRUE, NA,
NA, NA, NA, NA, TRUE) %>% as.matrix(),
block = tribble(~Cl, ~Vd, ~ka, ~Vp, ~Q,
FALSE, NA, NA, NA, NA,
NA, FALSE, NA, NA, NA,
NA, NA, TRUE, NA, NA,
NA, NA, NA, FALSE, NA,
NA, NA, NA, NA, FALSE) %>% as.matrix())
headers <- list(list(name = "ID", use = "identifier", type = NULL),
list(name = "TIME", use = "time", type = NULL),
list(name = "DV", use = "observation", type = "continuous"),
list(name = "DVID", use = "observationtype", type = NULL),
list(name = "ADM", use = "administration", type = NULL),
list(name = "AMT", use = "amount", type = NULL),
list(name = "EVID", use = "eventidentifier", type = NULL),
list(name = "MDV", use = "missingdependentvariable", type = NULL),
list(name = "AGE", use = "covariate", type = "continuous"),
list(name = "AGE_centered", use = "covariate", type = "continuous"),
list(name = "SEX", use = "covariate", type = "categorical"),
list(name = "WEIGHT", use = "covariate", type = "continuous"),
list(name = "BMI", use = "covariate", type = "continuous"))
theta <- tribble(~NAME, ~TRANS, ~INIT, ~LB, ~UB, ~EST,
"Cl", "logNormal", 0.2, NA, NA, TRUE,
"Vd", "logNormal", 20, NA, NA, TRUE,
"ka", "logNormal", 0.2, NA, NA, TRUE)
theta_intervals <- list(
Cl = c(0.25*theta$INIT[theta$NAME == "Cl"], 4*theta$INIT[theta$NAME == "Cl"]),
#Vd = c(0.5*theta$INIT[theta$NAME == "Vd"], 2*theta$INIT[theta$NAME == "Vd"]),
ka = c(1.25*theta$INIT[theta$NAME == "ka"], 1.5*theta$INIT[theta$NAME == "ka"])
)
ruv <- list(YNAME = "y1",
DVID = 1,
TRANS = "normal",
PRED = "Cc",
ERR = "proportional",
INIT = 1,
EST = TRUE)
n_starts <- 20
path <- tempdir()
sg_multistart(
mod = mod,
data = data,
headers = headers,
ruv = ruv,
theta = theta,
re = re,
occ = re,
n_starts = n_starts,
theta_intervals = theta_intervals,
path = path,
project_name = "multistart_test_project"
)
#> Error: cannot open file '/tmp/RtmpLedq7K/temp_libpath8b6abff614d/SimuRg/R/SimuRg.rdb': No such file or directory
clr_files <- list.files(path, full.names = TRUE)
unlink(clr_files, recursive = TRUE, force = TRUE)
# }