% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sg-modbuild.R
\name{sg_modbuild}
\alias{sg_modbuild}
\title{Build estimation model scenarios}
\usage{
sg_modbuild(
  mod_lst,
  data,
  headers,
  ruv_lst,
  theta_lst,
  re_lst,
  path,
  occ_lst,
  covs_lst = NULL,
  task_lst = NULL,
  opt_name = "Simurg",
  project_name = "my_project"
)
}
\arguments{
\item{mod_lst}{List of model file paths or model identifiers 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_lst}{List specifying residual unexplained variability (RUV) structures.
Each element contains RUV properties (e.g., \code{YNAME}, \code{ERR}) and mapping to data.}

\item{theta_lst}{List of tibbles describing population parameter properties.
Each tibble should contain columns such as \code{NAME}, \code{INIT}, and \code{EST}.}

\item{re_lst}{List of random effects (RE) specifications.
Each element includes matrices \code{init} and \code{est} defining initial and estimated covariance structures.}

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

\item{occ_lst}{List of occasion effect matrices.
Each element includes \code{init} and \code{est} matrices defining inter-occasion variability.}

\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{task_lst}{Optional list defining additional tasks or configuration options for each scenario. Default is NULL.}

\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"}.}
}
\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{
Constructs and exports multiple model configuration scenarios by combining population parameters,
random effects, residual variability, occasion effects, and covariate assignments.
Each scenario is defined by unique combinations of these model components and exported as \code{.mlxtran} files.
Additionally, a summary CSV file describing all scenarios is generated.
}
\details{
This function automates the construction of multiple model configurations for model evaluation,
sensitivity analysis, or scenario testing. It expands parameter and variability definitions,
constructs all possible combinations, and exports model specifications for external fitting tools.
}
\examples{
\donttest{
library(dplyr)
folder_path <- system.file("extdata", package = "SimuRg")
mod_lst <- list(paste(folder_path, "/models/model_PK_1c.txt", sep = "/"),
                  paste(folder_path, "/models/model_PK_2c.txt", sep = ""))

### path to the dataset
data <- paste(folder_path, "datasets", "dspk-warf.csv", sep = "/")
re_lst_1 <- list(
              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"))

ruv_lst_2 <- list(
  # structural model 1
 list(
   list(YNAME = "y1",
        DVID = 1,
        TRANS = "normal",
        PRED = "Cc",
        ERR = list("constant", "proportional", "combined1"),
         # options to test (can be length = 1, i.e., "constant" or "combined1")
        INIT = list(1, 1, c(1, 1)),
         # options to test (can be length = 1, i.e., 1 or c(1, 1))
        EST = list(TRUE, TRUE, c(TRUE, TRUE)))
        # options to test (can be length = 1, i.e., T or c(T, T))BLQM = NULL))
 ),
 # structural model 2
 list(
   list(YNAME = "y1",
        DVID = 1,
        TRANS = "normal",
        PRED = "Cc",
        ERR = list("constant", "proportional"),
        # options to test (can be length = 1, i.e., "constant" or "combined1")
        INIT = list(1, 1), # options to test (can be length = 1, i.e., 1 or c(1, 1))
        EST = list(TRUE, TRUE))
         # options to test (can be length = 1, i.e., T or c(T, T))BLQM = NULL))
 )
)

theta_lst_2 <- list(
 # structural model 1
 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),
 # structural model 2
 tribble(~NAME, ~TRANS, ~INIT, ~LB, ~UB, ~EST,
         "Cl", "logNormal", 0.2, NA, NA, TRUE,
         "Vd", c("Normal", "logNormal"), c(10, 20, 30), NA, NA, TRUE,
         "ka", "logNormal", c(0.2, 0.1, 0.5), NA, NA, TRUE,
         # INIT could be length > 1
         "Vp", c("Normal", "logNormal"), 10, NA, NA, TRUE,
         "Q", "logNormal", 5, NA, NA, TRUE))

path <- tempdir()
sg_modbuild(
 mod_lst = mod_lst[1],
 data = data,
 headers = headers,
 ruv_lst = ruv_lst_2,
 theta_lst = theta_lst_2,
 re_lst = re_lst_1,
 occ_lst = re_lst_1,
 covs_lst = NULL,
 path = path,
 project_name = "tests_test_project"
)
clr_files <- list.files(path, full.names = TRUE)
unlink(clr_files, recursive = TRUE, force = TRUE)
}

}
