Convert Monolix project output to R objects

Reads and parses Monolix project output files (.mlxtran and associated data files) into a structured list of SimuRg objects including parameter estimates, individual predictions, residuals, and diagnostic information.

Usage

sg_converter(folder_path, proj_name, save_file = FALSE)

Arguments

folder_path: Character string. Path to the directory containing Monolix project files.
proj_name: Character string. Name of the Monolix project (without file extension).
save_file: Logical. If TRUE, saves GCO and GFO JSON files to folder_path with names <proj_name>_GCO.json and <proj_name>_GFO.json, and also saves two RData files: <proj_name>_GCO.RData (object gco) and <proj_name>_GFO.RData (object gfo).

Value

Named list with GCO and GFO components.

Details

This function serves as a bridge between Monolix output and R by parsing the .mlxtran file and associated data files to create a comprehensive R object containing all relevant model outputs. This facilitates further analysis, visualization, and reporting in R.

The function automatically detects and imports various components of Monolix output including population parameters, individual parameters, covariates, and diagnostic metrics.

If save_file = TRUE, the function additionally writes GCO and GFO JSON files and .RData files to folder_path.

Examples

# \donttest{
library(stringr)
# Convert Monolix project results
test_folder <- system.file("extdata", "Monolix_objects", package = "SimuRg")
if (substr(test_folder, nchar(test_folder), nchar(test_folder)) != "/")
  test_folder <- str_c(test_folder, "/")
pro_name <- "proj-solo"
result <- sg_converter(folder_path = test_folder, proj_name = pro_name)
#> Detected model structure:1comp_ka
#> Omega parameters: omega_ka, omega_Cl
#> Random effect parameters:ka, Cl
#> Using Monte Carlo simulation with n_sim = 1000
#> Extracted parameter distributions: 3 parameters
#>   %s: %s (typical=%.2f, sd=%.2f)
#> CllogNormalCl_popomega_Cl
#>   %s: %s (typical=%.2f, sd=%.2f)
#> VlogNormalV_popNA
#>   %s: %s (typical=%.2f, sd=%.2f)
#> kalogNormalka_popomega_ka
#> Joining with `by = join_by(id)`
# save(results, file = "./models/simurg_object/Warfarin_PK.RData")
# Access individual predictions
head(result$GFO$SDTAB)
#> # A tibble: 6 × 12
#>      ID  TIME      DV  DVID DVNAME    PRED   IPRED       RES      IRES    WRES
#>   <dbl> <dbl>   <dbl> <dbl> <chr>    <dbl>   <dbl>     <dbl>     <dbl>   <dbl>
#> 1     1  0.25 0.00976     1 Cc     0.00874 0.00880 -0.00103  -0.000963 -0.157 
#> 2     1  0.5  0.0159      1 Cc     0.0173  0.0174   0.00139   0.00150   0.108 
#> 3     1  1    0.0342      1 Cc     0.0339  0.0340  -0.000321 -0.000167 -0.0134
#> 4     1  2    0.0611      1 Cc     0.0651  0.0651   0.00395   0.00401   0.0795
#> 5     1  3    0.103       1 Cc     0.0938  0.0935  -0.00898  -0.00925  -0.113 
#> 6     1  6    0.170       1 Cc     0.166   0.164   -0.00390  -0.0063   -0.0299
#> # ℹ 2 more variables: IWRES <dbl>, MDV <dbl>

# View parameter estimates
print(result$GFO$SUMTAB)
#> # A tibble: 6 × 13
#> # Groups:   PAR [6]
#>   PAR        VALUE TYPE   DISTRIBUTION EST        SE   RSE    CV     LCI     UCI
#>   <chr>      <dbl> <chr>  <chr>        <chr>   <dbl> <dbl> <dbl>   <dbl>   <dbl>
#> 1 ka_pop    0.0673 Typic… logNormal    ESTI… 0.00255 3.79   NA    0.0623  0.0723
#> 2 V_pop    19.1    Typic… logNormal    ESTI… 0.0991  0.520  NA   18.9    19.3   
#> 3 Cl_pop    0.279  Typic… logNormal    ESTI… 0.0123  4.41   NA    0.255   0.303 
#> 4 omega_ka  0.373  Rando… NA           ESTI… 0.0265  7.09   38.6  0.321   0.425 
#> 5 omega_Cl  0.440  Rando… NA           ESTI… 0.0324  7.36   46.2  0.376   0.503 
#> 6 Cc_b      0.0808 Resid… normal       ESTI… 0.00153 1.90   NA    0.0778  0.0838
#> # ℹ 3 more variables: ETAshrinkage_sd <dbl>, ETAshrinkage_var <dbl>,
#> #   EPSshrinkage_sd <dbl>

# Check objective function value
print(result$GFO$OFV)
#> # A tibble: 1 × 4
#>       LL    AIC    BIC   BICc
#>    <dbl>  <dbl>  <dbl>  <dbl>
#> 1 -9532. -9520. -9504. -9493.
# }