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

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 (character / 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 human-readable 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

Last updated: October 09, 2026