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
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.mlxtranproject file. IfNULL(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 separateDescriptioncolumn immediately to the right of theTestedcolumn. Keys must match theRunlabels of the output (e.g.c("Model 1" = "Base covariate model", "Model 17" = "Final model")). Unmatched rows getNA; 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) IfTRUE, 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. DefaultFALSE(show every evaluated model). Applies only to COSSAC/SCM; ignored for SAMBA. -
roundDigits(integer) Number of digits for rounding numeric values. Default is2. -
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 toroundDigitssignificant figures. Small values (< 1) automatically get more decimal places. -
"significantFigures"- Standard significant-figures rounding: the value is rounded toroundDigitstotal 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 leastroundDigitsdigits, 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) IfTRUE(default), applies report-ready column labels. -
mock(logical) IfTRUE, masks values for documentation/examples:LL/BICc/dLL/dBICc/p.valuebecome placeholders (e.g."xx.xx");Descriptionis blanked; real covariate names inTestedandCovariateModel(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 areRun,Reference,Step, and theSignificant/Improved/BestModelflags. DefaultFALSE.
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
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
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