% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sg-multistart.R
\name{sg_multistart}
\alias{sg_multistart}
\title{Build multistart scenarios with varying initial values}
\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{
\item{mod}{Model file path or model identifier used for scenario generation.}

\item{data}{Character string. Path to the dataset used in model fitting or simulation.}

\item{headers}{Predefined list of dataset column names (e.g., ID, TIME, DV, etc.) used by the modeling framework.}

\item{ruv}{Residual unexplained variability (RUV) structure.
Each element contains RUV properties (e.g., \code{YNAME}, \code{ERR}) and mapping to data.}

\item{theta}{Tibble describing population parameter properties.
Tibble should contain columns such as \code{NAME}, \code{INIT}, and \code{EST}.}

\item{re}{Random effects (RE) specification.
Includes matrices \code{init} and \code{est} defining initial and estimated covariance structures.}

\item{occ}{Occasion effect matrices.
Includes \code{init} and \code{est} matrices defining inter-occasion variability.}

\item{path}{Character. Directory path where output files (CSV summary and model files) will be written. Default is current working directory.}

\item{covs_lst}{Optional list describing covariate-parameter relationships.
Each element should include fields such as \code{PAR}, \code{COVNAME}, and \code{EST} indicating inclusion in the model.}

\item{opt_name}{Character. Optimization engine name (e.g., \code{"Monolix"}, \code{"Simurg"}). Default \code{"Simurg"}.}

\item{project_name}{Character. Base name for the exported project files. Default \code{"my_project"}.}

\item{n_starts}{Number of multistart runs (number of initial value scenarios).}

\item{theta_intervals}{Optional data frame specifying sampling
intervals for initial values. Must contain columns
\code{NAME}, \code{lower}, and \code{upper}.
If \code{NULL}, intervals are derived from \code{interval_factor}.}

\item{interval_factor}{Numeric vector of length 2 specifying
multiplicative lower and upper bounds factors relative to original
\code{INIT} values (default \code{c(0.2, 5)}).}

\item{vary_params}{List of parameters which inital values are varied.
Default value implies all parameters are varied. If \code{theta_interval} is specified,
list of parameters is taken from \code{theta_interval}}

\item{seed}{Optional random seed for reproducible sampling of
initial values. If \code{NULL}, the global RNG state is not modified.}
}
\value{
The function writes two types of outputs to the specified \code{path}:
\itemize{
\item A CSV file (\code{scenarios_info.csv}) summarizing all generated scenarios with columns:
\describe{
\item{scenario_number}{Unique index of the scenario.}
\item{model}{Model file or path used in the scenario.}
\item{data}{Path to the dataset used.}
\item{theta}{Active population parameters and initial values used.}
\item{RUV}{Residual error structure(s) used.}
\item{RE}{Random effect and correlation terms included.}
\item{OCC}{Active occasion effects.}
\item{COVS}{Included covariate-parameter relationships.}
}
\item Individual \code{.mlxtran} model files for each generated scenario,
named according to the pattern \verb{<project_name>_<i>.mlxtran}.
}
}
\description{
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 \code{.mlxtran} file
is generated. A summary table describing all multistart scenarios is written
to disk.
}
\details{
For each start:
\itemize{
\item Population parameter initial values \code{INIT} for
estimated parameters are sampled uniformly.
\item A scenario summary is stored.
\item The corresponding \code{.mlxtran} project files are written.
}

If \code{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")

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"
)
clr_files <- list.files(path, full.names = TRUE)
unlink(clr_files, recursive = TRUE, force = TRUE)
}

}
