MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableCovariateModelBuilding()

Returns a reporting-ready summary table of an automatic covariate model-building run (COSSAC, SCM, or SAMBA) for a Monolix project. Each row is one evaluated model, with its covariate structure, objective function value (OFV = −2·log-likelihood), BICc, and the change relative to its reference model. Columns adapt automatically to the strategy and selection criterion (LRT p-values/significance, or BICc improvement), and the best model(s) are flagged. Supports row sorting, criterion filtering, a compact "best model per step" view, and custom descriptions.

Usage

R
tableCovariateModelBuilding(projectFile             = NULL,
                            customDescriptions      = NULL,
                            filterCriteria          = c("none", "LL", "BICc"),
                            sortBy                  = c("index", "BICc", "LL", "pValue"),
                            displayBestModelPerStep = FALSE,
                            roundDigits             = 2,
                            roundMethod             = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                            prettyLabels            = TRUE,
                            mock                    = FALSE)

Arguments

  • projectFile (character) Path to a Monolix .mlxtran project file. If NULL (default), uses the currently loaded project. Model building must already have been run.

  • customDescriptions (named character vector/ data.frame) Named vector or 2-column data frame mapping model labels → descriptive text, added as a separate Description column immediately to the right of the Tested column. Keys must match the Run labels of the output (e.g. c("Model 1" = "Base covariate model", "Model 17" = "Final model")). Unmatched rows get NA; keys matching no row are ignored with a message.

  • filterCriteria (character) Which criteria columns to display:

    • "none" (default) - show both OFV/−2LL and BICc columns (and their deltas)

    • "LL" - show only OFV/−2LL columns (removes BICc and dBICc)

    • "BICc" - show only BICc columns (removes LL and dLL)

  • sortBy (character) Row order:

    • "index" (default) - keep the algorithm's model order

    • "BICc" - sort by BICc (lowest first = best)

    • "LL" - sort by OFV/−2LL (lowest first)

    • "pValue" - sort by LRT p-value, smallest first (LRT criterion only)

    For stepwise strategies (COSSAC/SCM), sorting stays within each step group (round), forward and backward phases, and repeated rounds, are never mixed. SAMBA has no steps and is sorted globally.

  • displayBestModelPerStep (logical) If TRUE, reduces the table to the accepted best model per step group plus the Base (start) model, giving a compact view of the actual model-building path. Winner selection is direction-aware under LRT (forward = smallest p-value; backward = largest p-value) and lowest-BICc under the BICc criterion. The winner is kept only if the step was accepted; dead-end rounds are dropped. Default FALSE (show every evaluated model). Applies only to COSSAC/SCM; ignored for SAMBA.

  • roundDigits (integer) Number of digits for rounding numeric values. Default is 2.

  • roundMethod (character) How numeric values are rounded. roundDigits controls the number of digits in each case. Options:

    • "monolixSuiteRounding" (default) - Mirrors MonolixSuite display. The integer part is kept exactly as-is, and only the fractional part is rounded to roundDigits significant figures. Small values (< 1) automatically get more decimal places.

    • "significantFigures" - Standard significant-figures rounding: the value is rounded to roundDigits total significant digits, zeroing non-significant digits before the decimal for large numbers.

    • "significantFiguresPreserved" - Like "significantFigures", but never zeroes digits before the decimal. Once the integer part already has at least roundDigits digits, the value is simply rounded to the nearest whole number instead of being zeroed out.

    • "none" - No rounding; values are returned as-is.

  • prettyLabels (logical) If TRUE (default), applies report-ready column labels.

  • mock (logical) If TRUE, masks values for documentation/examples: LL/BICc/dLL/dBICc/p.value become placeholders (e.g. "xx.xx"); Description is blanked; real covariate names in Tested and CovariateModel (e.g. "WT on CL", "CL~WT+SEX") are replaced with generic labels ("Covariate01", "Covariate02"…) via one consistent mapping. Parameter names (e.g. CL, V) are kept, as are Run, Reference, Step, and the Significant/Improved/BestModel flags. Default FALSE.

Returns: A data frame with one row per evaluated model (columns without information for the chosen strategy/criterion are dropped): Run (model label); Reference (reference model for the deltas); Tested (parameter–covariate relationship, COSSAC/SCM); Description (only if customDescriptions supplied); Step (Base/Forward/Backward, COSSAC/SCM); CovariateModel (compact covariate structure, "(no covariates)" if none); LL (OFV, −2·log-likelihood); BICc; dLL, dBICc (change vs the reference); p.value, Significant (LRT criterion, COSSAC/SCM, direction-aware); Improved (BICc criterion and SAMBA); and BestModel ("Yes" for the best model). The best_per_step attribute carries the accepted per-step winners for style_tfl() highlighting.

Examples

Covariate model building table with custom descriptions

R
loadProject(paste0(paste0(getDemoPath(),"/1.creating_and_using_models/1.1.libraries_of_models/warfarinPK_project.mlxtran")))

addContinuousTransformedCovariate(logtAge    = "log(age/30)")
addContinuousTransformedCovariate(logtWeight = "log(wt/70)")
  
mbSettings <- getModelBuildingSettings()
mbSettings$covariates <- c("sex", "logtAge", "logtWeight")
mbSettings$relationships[1,] = c("Tlag", "sex",        FALSE)
mbSettings$relationships[2,] = c("Tlag", "logtAge",    FALSE)
mbSettings$relationships[3,] = c("Tlag", "logtWeight", FALSE)
mbSettings$useLin = TRUE
mbSettings$strategy = "cossac"

runModelBuilding(settings = mbSettings)

tableCovariateModelBuilding(
    prettyLabels       = FALSE,
    customDescriptions = c(
      "Model 1" = "Base",
      "Model 2" = "Weight on V",
      "Model 3" = "+ Weight on Cl",
      "Model 4" = "+ Age on Cl")
)
#>     Run Reference           Tested    Description    Step              CovariateModel     LL   BICc    dLL  dBICc p.value BestModel Significant
#> Model 1                                      Base    Base             (no covariates) 654.51 701.43     NA     NA      NA                      
#> Model 2   Model 1  logtWeight on V    Weight on V Forward                V~logtWeight 627.89 678.27 -26.62 -23.16 2.5e-07       Yes         Yes
#> Model 3   Model 2 logtWeight on Cl + Weight on Cl Forward Cl~logtWeight, V~logtWeight 622.15 676.00  -5.74  -2.27 1.7e-02                    No
#> Model 4   Model 2    logtAge on Cl    + Age on Cl Forward    Cl~logtAge, V~logtWeight 624.52 678.37  -3.36   0.10 6.7e-02                    No

R
loadProject(paste0(paste0(getDemoPath(),"/1.creating_and_using_models/1.1.libraries_of_models/warfarinPK_project.mlxtran")))
  
addContinuousTransformedCovariate(logtAge    = "log(age/30)")
addContinuousTransformedCovariate(logtWeight = "log(wt/70)")
  
mbSettings <- getModelBuildingSettings()
mbSettings$covariates <- c("sex", "logtAge", "logtWeight")
mbSettings$relationships[1,] = c("Tlag", "sex",        FALSE)
mbSettings$relationships[2,] = c("Tlag", "logtAge",    FALSE)
mbSettings$relationships[3,] = c("Tlag", "logtWeight", FALSE)
mbSettings$useLin = TRUE
mbSettings$strategy = "scm"

runModelBuilding(settings = mbSettings)

tableCovariateModelBuilding()
#>      Run Reference\nModel Tested\nRelationship     Step                                   Covariate\nModel OFV\n(-2LL)   BICc     ΔOFV  ΔBICc p-value Best\nModel Significant
#>  Model 1                                           Base                                    (no covariates)      654.51 701.43       NA     NA      NA                        
#>  Model 2          Model 1            sex on ka  Forward                                             ka~sex      653.33 703.71  -1.1800   2.29 2.8e-01                      No
#>  Model 3          Model 1        logtAge on ka  Forward                                         ka~logtAge      653.05 703.44  -1.4600   2.01 2.3e-01                      No
#>  Model 4          Model 1     logtWeight on ka  Forward                                      ka~logtWeight      654.26 704.65  -0.2500   3.22 6.2e-01                      No
#>  Model 5          Model 1             sex on V  Forward                                              V~sex      638.84 689.22 -15.6700 -12.21 7.5e-05                     Yes
#>  Model 6          Model 1         logtAge on V  Forward                                          V~logtAge      653.44 703.82  -1.0700   2.39 3.0e-01                      No
#>  Model 7          Model 1      logtWeight on V  Forward                                       V~logtWeight      627.89 678.27 -26.6200 -23.16 2.5e-07                     Yes
#>  Model 8          Model 1            sex on Cl  Forward                                             Cl~sex      653.52 703.90  -0.9900   2.47 3.2e-01                      No
#>  Model 9          Model 1        logtAge on Cl  Forward                                         Cl~logtAge      651.36 701.74  -3.1500   0.31 7.6e-02                      No
#> Model 10          Model 1     logtWeight on Cl  Forward                                      Cl~logtWeight      648.47 698.86  -6.0400  -2.57 1.4e-02                     Yes
#> Model 11          Model 7            sex on ka  Forward                               V~logtWeight, ka~sex      627.37 681.23  -0.5100   2.95 4.7e-01                      No
#> Model 12          Model 7        logtAge on ka  Forward                           V~logtWeight, ka~logtAge      627.29 681.14  -0.6000   2.87 4.4e-01                      No
#> Model 13          Model 7     logtWeight on ka  Forward                        V~logtWeight, ka~logtWeight      626.69 680.54  -1.2000   2.27 2.7e-01                      No
#> Model 14          Model 7             sex on V  Forward                                   V~logtWeight+sex      627.26 681.11  -0.6200   2.84 4.3e-01                      No
#> Model 15          Model 7         logtAge on V  Forward                               V~logtAge+logtWeight      627.45 681.31  -0.4300   3.03 5.1e-01                      No
#> Model 16          Model 7            sex on Cl  Forward                               Cl~sex, V~logtWeight      626.89 680.74  -1.0000   2.46 3.2e-01                      No
#> Model 17          Model 7        logtAge on Cl  Forward                           Cl~logtAge, V~logtWeight      624.52 678.37  -3.3600   0.10 6.7e-02                      No
#> Model 18          Model 7     logtWeight on Cl  Forward                        Cl~logtWeight, V~logtWeight      622.15 676.00  -5.7400  -2.27 1.7e-02                     Yes
#> Model 19         Model 18            sex on ka  Forward                Cl~logtWeight, V~logtWeight, ka~sex      628.20 685.52   6.0500   9.52 1.0e+00                      No
#> Model 20         Model 18        logtAge on ka  Forward            Cl~logtWeight, V~logtWeight, ka~logtAge      621.67 678.99  -0.4800   2.99 4.9e-01                      No
#> Model 21         Model 18     logtWeight on ka  Forward         Cl~logtWeight, V~logtWeight, ka~logtWeight      621.88 679.20  -0.2700   3.20 6.0e-01                      No
#> Model 22         Model 18             sex on V  Forward                    Cl~logtWeight, V~logtWeight+sex      622.22 679.53   0.0690   3.53 1.0e+00                      No
#> Model 23         Model 18         logtAge on V  Forward                Cl~logtWeight, V~logtAge+logtWeight      622.02 679.34  -0.1300   3.34 7.2e-01                      No
#> Model 24         Model 18            sex on Cl  Forward                    Cl~logtWeight+sex, V~logtWeight      620.19 677.51  -1.9600   1.51 1.6e-01                      No
#> Model 25         Model 18        logtAge on Cl  Forward                Cl~logtAge+logtWeight, V~logtWeight      617.68 675.00  -4.4700  -1.00 3.4e-02                     Yes
#> Model 26         Model 25            sex on ka  Forward        Cl~logtAge+logtWeight, V~logtWeight, ka~sex      617.02 677.81  -0.6600   2.81 4.2e-01                      No
#> Model 27         Model 25        logtAge on ka  Forward    Cl~logtAge+logtWeight, V~logtWeight, ka~logtAge      617.69 678.47   0.0072   3.47 1.0e+00                      No
#> Model 28         Model 25     logtWeight on ka  Forward Cl~logtAge+logtWeight, V~logtWeight, ka~logtWeight      617.39 678.18  -0.2800   3.18 5.9e-01                      No
#> Model 29         Model 25             sex on V  Forward            Cl~logtAge+logtWeight, V~logtWeight+sex      616.50 677.28  -1.1800   2.28 2.8e-01                      No
#> Model 30         Model 25         logtAge on V  Forward        Cl~logtAge+logtWeight, V~logtAge+logtWeight      617.35 678.13  -0.3300   3.14 5.7e-01                      No
#> Model 31         Model 25            sex on Cl  Forward            Cl~logtAge+logtWeight+sex, V~logtWeight      616.46 677.24  -1.2200   2.25 2.7e-01                      No
#> Model 32         Model 25      logtWeight on V Backward                              Cl~logtAge+logtWeight      643.63 697.48  25.9500  22.49 3.5e-07                     Yes
#> Model 33         Model 25        logtAge on Cl Backward                        Cl~logtWeight, V~logtWeight      622.15 676.00   4.4700   1.00 3.4e-02                      No
#> Model 34         Model 18     logtWeight on Cl Backward                                       V~logtWeight      627.89 678.27   5.7400   2.27 1.7e-02         Yes          No

Last updated: