MonolixSuite in R
Auto Light Dark
Auto Light Dark

tablePopulationParameterEstimates()

Returns a reporting-ready table of Monolix population parameter estimates including fixed effects, inter-individual (IIV) and inter-occasion (IOV) variability, correlations, and residual error, together with their uncertainties. Supports long or wide layouts; optional RSE, confidence-interval, CV%, per-category fixed-effect, and bootstrap columns; and custom aliases/units/descriptions. The output carries attributes used by style_tfl() to auto-generate section headers.

Usage

R
tablePopulationParameterEstimates(projectFile        = NULL,
                                  customAliases      = NULL,
                                  customUnits        = NULL,
                                  customDescriptions = NULL,
                                  includeRSE         = TRUE,
                                  includeIIV         = TRUE,
                                  includeIOV         = TRUE,
                                  includeCI          = TRUE,
                                  includeCV          = TRUE,
                                  includeFEcategory  = FALSE,
                                  includeBootstrap   = FALSE,
                                  useWideFormat      = FALSE,
                                  stdErrMethod       = c("", "linearization", "stochasticApproximation"),
                                  roundDigits        = 3,
                                  roundMethod        = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                                  roundByParameter   = NULL,
                                  trailingZeros      = TRUE,
                                  prettyLabels       = TRUE,
                                  mock               = FALSE)

Arguments

  • projectFile (character) Path to a Monolix .mlxtran project file. If NULL (default), uses the currently loaded project.

  • customAliases (named character vector/ data.frame) Named vector or 2-column data frame mapping parameter names → custom display labels, e.g. c(ka_pop = "Absorption Rate", V_pop = "Volume"). Parameters not in the mapping keep their original names (with the _pop suffix removed). Supports [[sub:…]], [[sup:…]], ~italic~ formatting.

  • customUnits (named character vector/ data.frame) Named vector or 2-column data frame mapping parameter names → custom unit labels, e.g. c(ka_pop = "1/h", V_pop = "L", Cl_pop = "L/h"). Units are appended in parentheses, e.g. "Volume (L)".

  • customDescriptions (named character vector/ data.frame) Named vector or 2-column data frame mapping parameter names → descriptive text, e.g. c(Cl_pop = "Apparent clearance"). Added as a separate Description column to the right of Parameter (the Parameter value is unchanged); unmatched parameters get NA. Keys must match raw Monolix names (e.g. Cl_pop, omega_Cl, gamma_Cl, a, b). In wide format, descriptions for omega_* / gamma_* keys are not displayed (a message lists the unmatched keys).

  • includeRSE (logical) If TRUE (default), includes relative standard error (RSE) columns. Applies to both fixed and random effects in wide format.

  • includeIIV (logical) If TRUE (default), includes inter-individual variability (IIV) omega estimates in wide format. When FALSE, only fixed-effect estimates are shown in wide format (CV% can still appear if includeCV = TRUE).

  • includeIOV (logical) If TRUE (default), includes inter-occasion variability (IOV) gamma parameters. When FALSE, IOV parameters are excluded.

  • includeCI (logical) If TRUE, includes confidence-interval columns formatted as "(lower; upper)". Default TRUE. The percentile bounds in the column name follow the project's standard-error interval-level setting (e.g. CI_2.5_97.5 for 95%, CI_5_95 for 90%). Applies to both fixed and random effects in wide format.

  • includeCV (logical) If TRUE, includes coefficient of variation (CV%) for random effects. Default TRUE. In wide format, CV% appears as an additional column alongside omega estimates when includeIIV = TRUE.

  • includeFEcategory (logical) If TRUE, includes separate rows for fixed-effect values by categorical covariate level (the per-category estimates Monolix exposes via the withValuesByGroups option). Each per-category row has Section = "FE_CAT" and is grouped immediately after its parent fixed-effect rows. Default FALSE.

  • includeBootstrap (logical) If TRUE, includes bootstrap results: median estimate, confidence interval (e.g. Boot_CI_2.5_97.5), and RSE (if available). Bootstrap CI levels adapt to project settings (90%, 95%, 99%). Default FALSE. Requires a bootstrap analysis to have been run in Monolix.

  • useWideFormat (logical) If TRUE, presents random effects (IIV/IOV) in wide format with omega estimates as columns next to their corresponding fixed effects (sections: Fixed effects | Random effects, plus separate headers for Correlations and Residual error). If FALSE (default), uses long format where each parameter appears in its own row.

  • stdErrMethod (character) Standard-error method to use. Options: "" (default; uses whichever method the project has, preferring linear if both are available), "linearization", or "stochasticApproximation".

  • roundDigits (integer) Number of digits to display (default 3). Interpretation depends on roundMethod.

  • roundMethod (character) How numeric values are rounded:

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

  • roundByParameter (named numeric vector/ data.frame) Per-parameter rounding overrides on top of the global settings, either a named numeric vector of digits (c(ka_pop= 2, V_pop= 4)) or a 3-column data frame (parameter, digits, method). Unlisted parameters keep global settings (default NULL).

  • trailingZeros (logical) Only applies when roundMethod != "none". If TRUE(default), rounded concentration values are shown to the full precision implied by roundDigits/roundMethod, padding with trailing zeros (e.g. 1.20, 0.010); if FALSE, the minimal form is shown. With roundMethod = "none" raw values are shown unchanged.

  • prettyLabels (logical) If TRUE (default), applies pretty column names with newlines for better display (e.g. "Fixed Effect\nEstimate", "IIV\nSD"). If FALSE, uses simpler names without newlines (e.g. "FE_Estimate", "IIV_SD").

  • mock (logical) If TRUE, masks values for documentation/examples: every estimate/uncertainty column (Estimate/FE_Estimate, RSE, CV, the CI_* / IIV_* / IOV_* / Boot_* columns, in both layouts) becomes a placeholder (e.g. "xx.xx"; CI intervals become "(xx.xx; xx.xx)"). Section, Parameter, and Description are kept. Default FALSE.

Examples

Population parameter estimates in long format with uncertainty (default)

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

tablePopulationParameterEstimates()

#> Section  Parameter Estimate CV (%)                      95% CI       RSE (%)
#>      FE   Tlag_pop    0.737   <NA>              (0.440; 1.236)        27.773
#>      FE     ka_pop    1.122   <NA>              (0.686; 1.835)        26.312
#>      FE      V_pop    7.885   <NA>              (7.278; 8.543)         4.096
#>      FE     Cl_pop    0.134   <NA>              (0.121; 0.148)         5.129
#>      FE     R0_pop   97.229   <NA>            (95.948; 98.528)         0.677
#>      FE   kout_pop   0.0538   <NA>            (0.0495; 0.0585)         4.278
#>      FE   Imax_pop    1.000   <NA> (0.000000000000000222; NaN)           NaN
#>      FE   IC50_pop    1.155   <NA>              (0.902; 1.478)        12.741
#>     IIV omega_Tlag    0.645 71.773              (0.366; 1.136)        30.782
#>     IIV   omega_ka    0.693 78.525              (0.405; 1.186)        29.004
#>     IIV    omega_V    0.220 22.261              (0.169; 0.287)        13.725
#>     IIV   omega_Cl    0.285 29.045              (0.222; 0.365)        12.883
#>     IIV   omega_R0   0.0108  1.085           (0.00192; 0.0614)       160.907
#>     IIV omega_kout    0.123 12.317             (0.0812; 0.186)        21.801
#>     IIV omega_Imax    4.035  2.168        (0.00161; 10119.182) 843724000.000
#>     IIV omega_IC50    0.454 47.839              (0.341; 0.604)        14.833
#> RES_ERR         a1    0.291   <NA>              (0.213; 0.396)        16.133
#> RES_ERR         b1   0.0467   <NA>            (0.0322; 0.0678)        19.529
#> RES_ERR         a2    3.537   <NA>              (3.140; 3.984)         6.089

Population parameter estimates in wide format pairing each fixed effect with its inter-individual variability

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

tablePopulationParameterEstimates(
 useWideFormat = TRUE,
 includeIIV    = TRUE,
 includeCV     = TRUE)
#> Section Parameter Fixed Effect \nEstimate                      95% CI RSE (%) IIV\nSD IIV\nCV (%)          IIV\n95% CI  IIV\nRSE (%)
#>      FE  Tlag_pop                   0.737              (0.440; 1.236)  27.773   0.645      71.773       (0.366; 1.136)        30.782
#>      FE    ka_pop                   1.122              (0.686; 1.835)  26.312   0.693      78.525       (0.405; 1.186)        29.004
#>      FE     V_pop                   7.885              (7.278; 8.543)   4.096   0.220      22.261       (0.169; 0.287)        13.725
#>      FE    Cl_pop                   0.134              (0.121; 0.148)   5.129   0.285      29.045       (0.222; 0.365)        12.883
#>      FE    R0_pop                  97.229            (95.948; 98.528)   0.677  0.0108       1.085    (0.00192; 0.0614)       160.907
#>      FE  kout_pop                  0.0538            (0.0495; 0.0585)   4.278   0.123      12.317      (0.0812; 0.186)        21.801
#>      FE  Imax_pop                   1.000 (0.000000000000000222; NaN)     NaN   4.035       2.168 (0.00161; 10119.182) 843724000.000
#>      FE  IC50_pop                   1.155              (0.902; 1.478)  12.741   0.454      47.839       (0.341; 0.604)        14.833
#> RES_ERR        a1                   0.291              (0.213; 0.396)  16.133    <NA>        <NA>                 <NA>          <NA>
#> RES_ERR        b1                  0.0467            (0.0322; 0.0678)  19.529    <NA>        <NA>                 <NA>          <NA>
#> RES_ERR        a2                   3.537              (3.140; 3.984)   6.089    <NA>        <NA>                 <NA>          <NA>

Population parameter estimates with custom parameter aliases and units

R
loadProject(paste0(getDemoPath(),"/1.creating_and_using_models/1.1.libraries_of_models/warfarinPKPD_project.mlxtran"))
runScenario()
tablePopulationParameterEstimates(
  customAliases = c(
    ka_pop   = "k[[sub:a]]",   V_pop      = "V",            Cl_pop     = "CL",
    IC50_pop = "IC[[sub:50]]", kout_pop   = "k[[sub:out]]", Imax_pop   = "I[[sub:max]]",
    omega_ka   = "ω[[sub:ka]]",   omega_V    = "ω[[sub:V]]",    omega_Cl   = "ω[[sub:Cl]]",
    omega_IC50 = "ω[[sub:IC50]]", omega_kout = "ω[[sub:kout]]", omega_Imax = "ω[[sub:Imax]]",
    omega_Tlag = "ω[[sub:Tlag]]", omega_R0   = "ω[[sub:R0]]"),
  customUnits   = c(ka_pop = "1/h", V_pop = "L", Cl_pop = "L/h",
                    IC50_pop = "mg/L", R0_pop = "%", kout_pop = "1/h",
                    Imax_pop = "%")
)
#> Section           Parameter Estimate CV (%)                      95% CI       RSE (%)
#>      FE            Tlag_pop    0.737   <NA>              (0.440; 1.236)        27.773
#>      FE    k[[sub:a]] (1/h)    1.122   <NA>              (0.686; 1.835)        26.312
#>      FE               V (L)    7.885   <NA>              (7.278; 8.543)         4.096
#>      FE            CL (L/h)    0.134   <NA>              (0.121; 0.148)         5.129
#>      FE          R0_pop (%)   97.229   <NA>            (95.948; 98.528)         0.677
#>      FE  k[[sub:out]] (1/h)   0.0538   <NA>            (0.0495; 0.0585)         4.278
#>      FE    I[[sub:max]] (%)    1.000   <NA> (0.000000000000000222; NaN)           NaN
#>      FE IC[[sub:50]] (mg/L)    1.155   <NA>              (0.902; 1.478)        12.741
#>     IIV       ω[[sub:Tlag]]    0.645 71.773              (0.366; 1.136)        30.782
#>     IIV         ω[[sub:ka]]    0.693 78.525              (0.405; 1.186)        29.004
#>     IIV          ω[[sub:V]]    0.220 22.261              (0.169; 0.287)        13.725
#>     IIV         ω[[sub:Cl]]    0.285 29.045              (0.222; 0.365)        12.883
#>     IIV         ω[[sub:R0]]   0.0108  1.085           (0.00192; 0.0614)       160.907
#>     IIV       ω[[sub:kout]]    0.123 12.317             (0.0812; 0.186)        21.801
#>     IIV       ω[[sub:Imax]]    4.035  2.168        (0.00161; 10119.182) 843724000.000
#>     IIV       ω[[sub:IC50]]    0.454 47.839              (0.341; 0.604)        14.833
#> RES_ERR                  a1    0.291   <NA>              (0.213; 0.396)        16.133
#> RES_ERR                  b1   0.0467   <NA>            (0.0322; 0.0678)        19.529
#> RES_ERR                  a2    3.537   <NA>              (3.140; 3.984)         6.089

Population parameter estimates with a parameter description column

R
loadProject(paste0(getDemoPath(),"/1.creating_and_using_models/1.1.libraries_of_models/warfarinPKPD_project.mlxtran"))
runScenario()
tablePopulationParameterEstimates(
  customDescriptions = c(
    Tlag_pop   = "Absorption lag time",
    ka_pop     = "First-order absorption rate constant",
    V_pop      = "Apparent central volume of distribution",
    Cl_pop     = "Apparent clearance",
    R0_pop     = "Baseline response (prothrombin complex activity)",
    kout_pop   = "Response turnover rate constant",
    Imax_pop   = "Maximum inhibitory effect",
    IC50_pop   = "Concentration at half-maximal inhibition",
    omega_Tlag = "IIV of Tlag",
    omega_ka   = "IIV of ka",
    omega_V    = "IIV of V",
    omega_Cl   = "IIV of Cl",
    omega_R0   = "IIV of R0",
    omega_kout = "IIV of kout",
    omega_Imax = "IIV of Imax",
    omega_IC50 = "IIV of IC50",
    a1         = "Additive residual error (concentration)",
    b1         = "Proportional residual error (concentration)",
    a2         = "Additive residual error (response)"))

#>Section  Parameter                                      Description Estimate CV (%)                      95% CI       RSE (%)
#>      FE   Tlag_pop                              Absorption lag time    0.737   <NA>              (0.440; 1.236)        27.773
#>      FE     ka_pop             First-order absorption rate constant    1.122   <NA>              (0.686; 1.835)        26.312
#>      FE      V_pop          Apparent central volume of distribution    7.885   <NA>              (7.278; 8.543)         4.096
#>      FE     Cl_pop                               Apparent clearance    0.134   <NA>              (0.121; 0.148)         5.129
#>      FE     R0_pop Baseline response (prothrombin complex activity)   97.229   <NA>            (95.948; 98.528)         0.677
#>      FE   kout_pop                  Response turnover rate constant   0.0538   <NA>            (0.0495; 0.0585)         4.278
#>      FE   Imax_pop                        Maximum inhibitory effect    1.000   <NA> (0.000000000000000222; NaN)           NaN
#>      FE   IC50_pop         Concentration at half-maximal inhibition    1.155   <NA>              (0.902; 1.478)        12.741
#>     IIV omega_Tlag                                      IIV of Tlag    0.645 71.773              (0.366; 1.136)        30.782
#>     IIV   omega_ka                                        IIV of ka    0.693 78.525              (0.405; 1.186)        29.004
#>     IIV    omega_V                                         IIV of V    0.220 22.261              (0.169; 0.287)        13.725
#>     IIV   omega_Cl                                        IIV of Cl    0.285 29.045              (0.222; 0.365)        12.883
#>     IIV   omega_R0                                        IIV of R0   0.0108  1.085           (0.00192; 0.0614)       160.907
#>     IIV omega_kout                                      IIV of kout    0.123 12.317             (0.0812; 0.186)        21.801
#>     IIV omega_Imax                                      IIV of Imax    4.035  2.168        (0.00161; 10119.182) 843724000.000
#>     IIV omega_IC50                                      IIV of IC50    0.454 47.839              (0.341; 0.604)        14.833
#> RES_ERR         a1          Additive residual error (concentration)    0.291   <NA>              (0.213; 0.396)        16.133
#> RES_ERR         b1      Proportional residual error (concentration)   0.0467   <NA>            (0.0322; 0.0678)        19.529
#> RES_ERR         a2               Additive residual error (response)    3.537   <NA>              (3.140; 3.984)         6.089

Covariate model: population parameter estimates with per-category fixed effects

R
loadProject(paste0(getDemoPath(),"/5.models_for_individual_parameters/5.2.covariate_model/phenobarbital_project.mlxtran"))
runScenario()
tablePopulationParameterEstimates(includeFEcategory = TRUE)

> tablePopulationParameterEstimates(includeFEcategory = TRUE)
#> Section          Parameter Estimate CV (%)             95% CI RSE (%)
#>      FE              V_pop    1.244   <NA>     (1.075; 1.439)   7.465
#>      FE beta_V_tAPGAR_High    0.262   <NA>    (0.0385; 0.485)  43.511
#>      FE  beta_V_tAPGAR_Low    0.132   <NA>    (-0.201; 0.465) 128.758
#>      FE              k_pop  0.00487   <NA> (0.00450; 0.00527)   4.051
#>  FE_CAT      V_tAPGAR_High    1.616   <NA>     (1.363; 1.916)   8.725
#>  FE_CAT       V_tAPGAR_Low    1.419   <NA>     (1.051; 1.916)  15.589
#>  FE_CAT       V_tAPGAR_Med    1.244   <NA>     (1.075; 1.439)   7.465
#>     IIV            omega_V    0.397 41.325     (0.330; 0.477)   9.451
#>     IIV            omega_k    0.146 14.656    (0.0876; 0.243)  27.316
#> RES_ERR                  b    0.112   <NA>    (0.0955; 0.131)   8.073

Model with inter-occasion variability: estimates including IOV in wide format

R
loadProject(paste0(getDemoPath(),"/5.models_for_individual_parameters/5.4.inter_occasion_variability/iov3_project.mlxtran"))
runScenario()
tablePopulationParameterEstimates(useWideFormat = TRUE)

#>[WARNING] No standard error estimation
#>       Section Parameter Fixed Effect \nEstimate IIV\nSD IIV\nCV (%) IOV\nSD IOV\nCV (%)
#>ka_pop      FE    ka_pop                   1.005   0.361      37.289    <NA>        <NA>
#>V_pop       FE     V_pop                   0.204   0.328      33.655 0.00739       0.739
#>Cl_pop      FE    Cl_pop                  0.0292   0.305      31.180    <NA>        <NA>
#>b      RES_ERR         b                  0.0979    <NA>        <NA>    <NA>        <NA>
#>Warning message:
#>No standard error estimates available (standard error estimation task not run). Setting includeRSE and includeCI to FALSE. 

Population parameter estimates with custom per-parameter rounding

R
loadProject(paste0(getDemoPath(),"/1.creating_and_using_models/1.1.libraries_of_models/warfarinPKPD_project.mlxtran"))
runScenario()
tablePopulationParameterEstimates(
  roundByParameter = c(Cl_pop = 4, omega_Cl = 2, omega_R0 = 5),
  trailingZeros    = FALSE)

#> Section  Parameter Estimate  CV (%)                      95% CI   RSE (%)
#>      FE   Tlag_pop    0.737    <NA>               (0.44; 1.236)    27.773
#>      FE     ka_pop    1.122    <NA>              (0.686; 1.835)    26.312
#>      FE      V_pop    7.885    <NA>              (7.278; 8.543)     4.096
#>      FE     Cl_pop   0.1335    <NA>            (0.1208; 0.1476)    5.1288
#>      FE     R0_pop   97.229    <NA>            (95.948; 98.528)     0.677
#>      FE   kout_pop   0.0538    <NA>            (0.0495; 0.0585)     4.278
#>      FE   Imax_pop        1    <NA> (0.000000000000000222; NaN)       NaN
#>      FE   IC50_pop    1.155    <NA>              (0.902; 1.478)    12.741
#>     IIV omega_Tlag    0.645  71.773              (0.366; 1.136)    30.782
#>     IIV   omega_ka    0.693  78.525              (0.405; 1.186)    29.004
#>     IIV    omega_V     0.22  22.261              (0.169; 0.287)    13.725
#>     IIV   omega_Cl     0.28   29.04                (0.22; 0.37)     12.88
#>     IIV   omega_R0 0.010848 1.08479       (0.0019178; 0.061357)   160.907
#>     IIV omega_kout    0.123  12.317             (0.0812; 0.186)    21.801
#>     IIV omega_Imax    4.035   2.168        (0.00161; 10119.182) 843724000
#>     IIV omega_IC50    0.454  47.839              (0.341; 0.604)    14.833
#> RES_ERR         a1    0.291    <NA>              (0.213; 0.396)    16.133
#> RES_ERR         b1   0.0467    <NA>            (0.0322; 0.0678)    19.529
#> RES_ERR         a2    3.537    <NA>               (3.14; 3.984)     6.089

Population parameter estimates with bootstrap confidence intervals

R
loadProject(paste0(getDemoPath(),"/5.models_for_individual_parameters/5.2.covariate_model/phenobarbital_project.mlxtran"))
runScenario()
runBootstrap(nbRuns=3, method="parametric", tasks=list("standardErrorEstimation"), useLin=FALSE)

tablePopulationParameterEstimates(
  includeBootstrap = TRUE,
  roundMethod      = "significantFiguresPreserved"
)

#> Section          Parameter Estimate CV (%)             95% CI RSE (%) Bootstrap\nMedian  Bootstrap\n95% CI Bootstrap\nRSE (%)
#>      FE              V_pop     1.24   <NA>       (1.08; 1.44)    7.46              1.26       (1.23; 1.31)               3.04
#>      FE beta_V_tAPGAR_High    0.262   <NA>    (0.0385; 0.485)    43.5             0.260     (0.251; 0.332)               15.9
#>      FE  beta_V_tAPGAR_Low    0.132   <NA>    (-0.201; 0.465)     129            0.0318    (-0.148; 0.136)               2224
#>      FE              k_pop  0.00487   <NA> (0.00450; 0.00527)    4.05           0.00493 (0.00481; 0.00495)               1.48
#>     IIV            omega_V    0.397   41.3     (0.330; 0.477)    9.45             0.393     (0.388; 0.471)               11.1
#>     IIV            omega_k    0.146   14.7    (0.0876; 0.243)    27.3            0.0926    (0.0895; 0.248)               63.2
#> RES_ERR                  b    0.112   <NA>    (0.0955; 0.131)    8.07             0.122     (0.106; 0.122)               7.59



See also

style_tfl


Last updated: