Generalized Control Object (GCO)

Generalized control object (GCO) stores the model setup, dataset mapping, and estimation options used for fitting or downstream simulation configuration.

Format

GCO

A named list with the following components:

headers

List of lists. One element per dataset column with fields: name (character, column name), use (character, Monolix column role such as "identifier", "time", "observation", "covariate", etc.), type (character or empty; for covariates: "continuous" or "categorical").

data

Character. Path to the source dataset file.

model

Character. Path to the structural model file (Monolix syntax).

task_opt

List. Task options passed to the fitter; empty list when not set.

covs

Character vector. Names of covariate columns detected in the dataset headers.

project_name

Character. Project or run name.

theta

List of lists or data frame. Population (typical) parameter definitions. Each record contains: NAME (character, parameter name without _pop suffix), TRANS (character, "normal", "logNormal", or "logitNormal"), INIT (numeric, initial or fixed value on the natural scale), EST (logical, whether the parameter is estimated). When passed to sg_fit(), a tibble with optional LB and UB for logit bounds is also accepted.

ruv

List, or list of lists for multiple observation types. Residual error model definition with fields: YNAME (character, longitudinal output name, e.g. "y1"), DVID (numeric, observation-type identifier), TRANS (character, residual distribution), PRED (character, prediction variable name), ERR (character, error model type such as "constant", "proportional", "combined1"), INIT (numeric vector of initial residual-error parameter values), EST (logical vector, estimation flags), BLQM (optional BLQ handling method; NULL when not used).

re

List with init and est numeric matrices. Between-subject variability: diagonal elements are initial variances of omega_* parameters, off-diagonal elements are covariances; est uses TRUE/FALSE/NA in the same layout as sg_fit() input.

occ

List with init and est matrices. Between-occasion variability in the same layout as re; all-zero/NA when occasion variability is not modeled.

modelText

Character. Full text of the structural model file.

Details

Create a GCO with sg_converter() from a Monolix project, or with sg_fit().

See also

GFO, GMO, sg_fit(), sg_converter(), read_smrg_ctrl()

Examples

# \donttest{
# Bundled GCO (Simurg fit configuration, JSON format)
gco_path <- system.file("extdata", "simurg_object", "sg_object.json",
                        package = "SimuRg")
gco <- read_smrg_ctrl(gco_path)
names(gco)
#>  [1] "model"        "data"         "headers"      "theta"        "ruv"         
#>  [6] "re"           "occ"          "covs"         "project_name" "task_opt"    
gco$project_name
#> [1] "my_project"
gco$theta
#>   NAME     TRANS INIT  EST
#> 1   Cl logNormal  0.2 TRUE
#> 2   Vd logNormal 20.0 TRUE
#> 3   ka logNormal  0.2 TRUE
gco$ruv
#> $YNAME
#> [1] "y1"
#> 
#> $DVID
#> [1] 1
#> 
#> $TRANS
#> [1] "normal"
#> 
#> $PRED
#> [1] "Cc"
#> 
#> $ERR
#> [1] "combined1"
#> 
#> $INIT
#> [1] 1 1
#> 
#> $EST
#> [1] TRUE TRUE
#> 
#> $BLQM
#> named list()
#> 
gco$re$init
#>      [,1] [,2] [,3]
#> [1,]    1    0    0
#> [2,]    0    0    0
#> [3,]    0    0    1
# }