MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableRunHistory()

Produces a reporting-ready summary table of the Monolix run history from a Sycomore project, model-selection criteria (OFV/log-likelihood and BICc), parent relationships, deltas to the parent run, ratings, and comments. Supports sorting by criterion, criterion filtering, and run masking for examples.

Requires the model-tree graph to have been defined in the Sycomore project, as the run hierarchy (parent/child relationships) is read from it.

Usage

R
tableRunHistory(sycomoreProjectFile,
                roundDigits    = 2,
                roundMethod    = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                sortByCriteria = c("LL", "BICc", "none"),
                filterCriteria = c("none", "LL", "BICc"),
                prettyLabels   = TRUE,
                mock           = FALSE)

Arguments

  • sycomoreProjectFile (character) Path to a Sycomore project file (.syc). Mandatory (no default). The project must contain a defined model-tree graph, the run hierarchy and parent/child relationships are read from it, and deltas to the parent run depend on it.

  • roundDigits (integer) Number of decimal places for rounding (default 3).

  • 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.

  • sortByCriteria (character) Which criterion to sort by:

    • "LL" (default) - sort by log-likelihood/OFV (lowest first = best model)

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

    • "none" - no sorting

    When both linearization and importance-sampling results are available, the method is auto-detected from the parent project.

  • filterCriteria (character) Which criteria columns to display:

    • "none" (default) - show all criteria columns (LL and BICc)

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

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

    When sorting by a criterion, filterCriteria must be "none" or match the sort criterion (e.g. sortByCriteria = "LL" with filterCriteria = "BICc" is an error).

  • prettyLabels (logical) If TRUE (default), applies report-ready column labels (e.g. "LL (Imp. Sampling)" instead of "LLis").

  • mock (logical) If TRUE, masks values for documentation/examples: the LL/BICc/delta columns become placeholders (e.g. "xx.xx"); Comments is blanked; Rating is masked (numeric → "xx.xx", non-numeric blanked); and Run/Parent (which hold real project/file names that may embed study, compound, or company identifiers) are relabeled generically ("project01", "project02"…) via one consistent mapping, so a Parent reference always matches the generic name of that project's own Run row. Path is rebuilt from the relabeled name (keeping only the file extension). Default FALSE.

Returns: A data frame with Run (project/run name); Parent (parent run name, empty for root projects); LLlin/LLis (log-likelihood from linearization / importance sampling); BICclin/BICcis (BICc from each method); dLLlin/dLLis and dBICclin/dBICcis (deltas vs the parent run); Comments (from the mlxtran file); and Rating (user rating from Sycomore). Columns that are all NA are automatically removed.

Examples

Sycomore project

R
prj <-"path/to/my/sycomoreProject/ModelComparison.syc"
tableRunHistory(sycomoreProjectFile = prj,
                filterCriteria = "LL") %>%
    select(-Comments, -Rating)

#>                                                      Run                                                     Project Path                              Parent Run LL\n(Linearization) LL\n(Imp. Sampling) ΔLL\n(Linearization)
#>                            r04_DoubleAbsorp2cmt_noSimAnn                            r04_DoubleAbsorp2cmt_noSimAnn.mlxtran                                r01_2cmt              286.36                  NA               -72.72
#>                                     r04_DoubleAbsorp2cmt                                     r04_DoubleAbsorp2cmt.mlxtran                                r01_2cmt              292.37                  NA               -66.71
#>                  r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2                  r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2.mlxtran                    r04_DoubleAbsorp2cmt              304.79                  NA                12.41
#> r06_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noEtaka2_noEtaF1 r06_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noEtaka2_noEtaF1.mlxtran r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2              305.35                  NA                 0.57
#>                                             r10_Tlag3cmt                                             r10_Tlag3cmt.mlxtran                            r02_Tlag2cmt              305.54                  NA               -32.30
#>         r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noSimAnn         r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noSimAnn.mlxtran           r04_DoubleAbsorp2cmt_noSimAnn              306.08                  NA                19.72
#>                                       r08_Tlag0order2cmt                                       r08_Tlag0order2cmt.mlxtran                          r07_0order2cmt              334.92                  NA                -6.69
#>                                    r02_Tlag2cmt_noSimAnn                                    r02_Tlag2cmt_noSimAnn.mlxtran                            r02_Tlag2cmt              337.03                  NA                -0.82
#>                                             r02_Tlag2cmt                                             r02_Tlag2cmt.mlxtran                                r01_2cmt              337.85              338.72               -21.24
#>                                           r07_0order2cmt                                           r07_0order2cmt.mlxtran                                r01_2cmt              341.62                  NA               -17.47
#>                                          r11_SigmAbs2cmt                                          r11_SigmAbs2cmt.mlxtran                                r01_2cmt              346.76                  NA               -12.32
#>                        r12_SigmAbs2cmt_noEtaTk0_notEtaka                        r12_SigmAbs2cmt_noEtaTk0_notEtaka.mlxtran                         r11_SigmAbs2cmt              349.50                  NA                 2.75
#>                                                 r01_2cmt                                                 r01_2cmt.mlxtran                                                      359.08                  NA                   NA
#>                                      r03_TransitCmt_2cmt                                      r03_TransitCmt_2cmt.mlxtran                                r01_2cmt              364.11                  NA                 5.03
#>                                       r09_WeibullAbs2cmt                                       r09_WeibullAbs2cmt.mlxtran                                r01_2cmt                  NA              335.87                   NA

tableRunHistory(sycomoreProjectFile = prj,
                prettyLabels        = FALSE) %>%
    select(-Comments)

#>                                                      Run                                                             Path                                  Parent  LLlin   LLis BICclin BICcis dLLlin dBICclin Rating
#>                            r04_DoubleAbsorp2cmt_noSimAnn                            r04_DoubleAbsorp2cmt_noSimAnn.mlxtran                                r01_2cmt 286.36     NA  360.23     NA -72.72   -44.05      0
#>                                     r04_DoubleAbsorp2cmt                                     r04_DoubleAbsorp2cmt.mlxtran                                r01_2cmt 292.37     NA  366.24     NA -66.71   -38.04      0
#>                  r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2                  r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2.mlxtran                    r04_DoubleAbsorp2cmt 304.79     NA  373.68     NA  12.41     7.44      0
#> r06_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noEtaka2_noEtaF1 r06_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noEtaka2_noEtaF1.mlxtran r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2 305.35     NA  369.28     NA   0.57    -4.40      0
#>                                             r10_Tlag3cmt                                             r10_Tlag3cmt.mlxtran                            r02_Tlag2cmt 305.54     NA  372.24     NA -32.30   -17.97      0
#>         r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noSimAnn         r05_DoubleAbsorp2cmt_noEtaTlag2_noEtaV2_noSimAnn.mlxtran           r04_DoubleAbsorp2cmt_noSimAnn 306.08     NA  374.97     NA  19.72    14.75      0
#>                                       r08_Tlag0order2cmt                                       r08_Tlag0order2cmt.mlxtran                          r07_0order2cmt 334.92     NA  387.29     NA  -6.69     0.47      0
#>                                    r02_Tlag2cmt_noSimAnn                                    r02_Tlag2cmt_noSimAnn.mlxtran                            r02_Tlag2cmt 337.03     NA  389.39     NA  -0.82    -0.82      0
#>                                             r02_Tlag2cmt                                             r02_Tlag2cmt.mlxtran                                r01_2cmt 337.85 338.72  390.21 391.09 -21.24   -14.07      0
#>                                           r07_0order2cmt                                           r07_0order2cmt.mlxtran                                r01_2cmt 341.62     NA  386.82     NA -17.47   -17.47      0
#>                                          r11_SigmAbs2cmt                                          r11_SigmAbs2cmt.mlxtran                                r01_2cmt 346.76     NA  399.13     NA -12.32    -5.16      0
#>                        r12_SigmAbs2cmt_noEtaTk0_notEtaka                        r12_SigmAbs2cmt_noEtaTk0_notEtaka.mlxtran                         r11_SigmAbs2cmt 349.50     NA  396.90     NA   2.75    -2.22      0
#>                                                 r01_2cmt                                                 r01_2cmt.mlxtran                                         359.08     NA  404.28     NA     NA       NA      0
#>                                      r03_TransitCmt_2cmt                                      r03_TransitCmt_2cmt.mlxtran                                r01_2cmt 364.11     NA  423.65     NA   5.03    19.36      0
#>                                       r09_WeibullAbs2cmt                                       r09_WeibullAbs2cmt.mlxtran                                r01_2cmt     NA 335.87      NA 383.55     NA       NA      0

Last updated: