MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableNCAParameters()

Returns a reporting-ready summary table of NCA parameters from a PKanalix project. Supports stratification by covariates and occasions, wide or vertical layouts, per-parameter rounding, (custom) aliases/units, and optional inclusion of individual subject values.

Usage

R
tableNCAParameters(projectFile          = NULL,
                   splitCovariates      = NULL,
                   splitCovariateLabels = NULL,
                   stratifyColumns      = FALSE,
                   selectParameters     = NULL,
                   metrics              = NULL,
                   useWideFormat        = TRUE,
                   includeIds           = FALSE,
                   filterCovariates     = NULL,
                   filterIds            = NULL,
                   roundDigits          = 3,
                   roundMethod          = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                   roundByParameter     = NULL,
                   trailingZeros        = TRUE,
                   units                = TRUE,
                   aliases              = TRUE,
                   customUnits          = NULL,
                   customAliases        = NULL,
                   prettyLabels         = TRUE,
                   mock                 = FALSE)

Arguments

  • projectFile (character) Path to a PKanalix project file (.pkx). If NULL (default), uses the currently loaded project; loads the given project if it differs from the active one.

  • splitCovariates (character vector) Covariate name(s) to stratify by, e.g. "TREAT" or c("TREAT","FOOD"). If NULL (default), no stratification — overall summaries only.

  • splitCovariateLabels (character vector) Custom labels for splitCovariates. If NULL (default), the original covariate names are used. Applied in both layouts: shown in the combined column headers when stratifyColumns = TRUE, and used to rename the split-covariate columns when stratifyColumns = FALSE.

  • stratifyColumns (logical) If TRUE, creates separate columns per covariate combination plus an "Overall" column. If FALSE (default), covariates appear as left-side columns. Only applies when splitCovariates is set and useWideFormat = FALSE.

  • selectParameters (character vector) NCA parameter names to include. If NULL (default), all parameters currently enabled in the project are used.

  • metrics (character vector) Summary statistics to include. If NULL (default), all available metrics are included. Accepted values (returned by getDescriptiveStatsMetrics(), in calculation order):

    • Counts: "N", "Nobs"

    • Range / percentiles: "min", "P05", "Q1", "median", "Q3", "P95", "max"

    • Central tendency & dispersion: "mean", "SD", "SE", "CV"

    • Geometric / harmonic: "geoMean", "geoSD", "geoCV", "harmMean"

    • Combined display metrics: "MeanSD", "MeanCV", "GeomCV", "GeomSD"

  • useWideFormat (logical) If TRUE (default), returns a wide table with one row per covariate level (PKanalix-like). If FALSE, returns a vertical table with Statistic as the first column.

  • includeIds(logical) If TRUE (with useWideFormat = FALSE), appends individual subject IDs and their values below the summary statistics, grouped by covariate when stratified, with a Section column created, identifying record type. Default FALSE.

  • filterCovariates (list) Named list of categorical covariates → allowed values, e.g. list(DOSE = c("100mg","200mg"), SEX = "Male"). If NULL (default), no covariate filtering is applied.

  • filterIds (character/numeric vector) Subject IDs to include. If NULL (default), no ID filtering is applied.

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

  • roundMethod (character) How numeric values are rounde:

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

    • "significantFigures" - Standard significant-figures rounding 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 roundDigits digits, the value is rounded to the nearest whole number.

    • "none" - No rounding.

  • roundByParameter (named numeric vector/ data.frame) Per-parameter rounding overrides on top of the global settings - either a named numeric vector of digits (c(Cmax = 2, AUClast = 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.

  • units (logical) If TRUE (default), units are appended to parameter names.

  • aliases (logical) If TRUE (default), parameter aliases (friendly names) are used instead of internal codes.

  • customUnits (named character vector/ data.frame) Named vector or 2-column data frame mapping parameters → custom unit labels, e.g. c(Cmax = "ng/mL", AUClast = "h*ng/mL").

  • customAliases (named character vector/ data.frame) Named vector or 2-column data frame mapping parameters → custom alias labels, e.g. c(Cmax = "C[[sub:max]]"). Supports [[sub:…]], [[sup:…]], ~italic~.

  • prettyLabels (logical) If TRUE (default), converts column names to report-ready labels (e.g. "CV" → "CV (%)").

  • mock (logical) If TRUE, masks values for documentation/examples (metric values become "xx.xx", covariate levels become "Category 1"…, IDs become "id1"…). Default FALSE.

Returns: A data frame combining standard NCA statistics with additional descriptive statistics for the selected parameters; when includeIds = TRUE, also individual per-subject values and a Section column distinguishing summary from individual records.

Examples

NCA parameter summary table in wide format stratified by covariate

R
initializeLixoftConnectors(software = "pkanalix")
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_units.pkx"))
runNCAEstimation()
tableNCAParameters(splitCovariates = "ROUTE",
                   selectParameters = c("AUCINF_obs", "AUClast", "Cmax", "Tmax"),
                   metrics         = c("N","min", "Q1", "MeanSD", "GeomCV", "median", "Q3", "max"),
                   roundDigits     = 2)

#>                   Parameter ROUTE N  Minimum       Q1 Arithmetic\nMean (SD) Geometric\nMean (CV %)   Median       Q3  Maximum
#>   AUC[[sub:0-inf]] (h*ng/L)    IV 9 211619.5 235754.4    256307.9 (30080.1)        254760.0 (11.7) 258291.7 276350.5 311510.7
#>   AUC[[sub:0-inf]] (h*ng/L)  ORAL 9 198896.2 209418.3    224476.3 (15956.2)         223960.7 (7.2) 229391.8 234382.1 246607.9
#> AUC[[sub:0-tlast]] (h*ng/L)    IV 9 210543.6 232684.9    253279.7 (28668.9)        251853.3 (11.3) 256543.9 272299.8 305269.7
#> AUC[[sub:0-tlast]] (h*ng/L)  ORAL 9 197327.7 208067.9    221734.0 (15099.8)         221268.0 (6.9) 226919.6 230836.8 243674.8
#>         C[[sub:max]] (ng/L)    IV 9   3406.7   3800.8        4046.9 (396.2)           4029.7 (9.8)   3955.8   4372.7   4672.3
#>         C[[sub:max]] (ng/L)  ORAL 9   2329.0   2360.9        2633.8 (351.5)          2614.0 (12.9)   2421.3   2985.0   3206.4
#>            T[[sub:max]] (h)    IV 9     0.08      0.2             1.2 (2.6)            0.4 (228.9)      0.2      0.5      8.0
#>            T[[sub:max]] (h)  ORAL 9      8.0     12.0            20.4 (7.9)            18.8 (48.9)     24.0     24.0     32.0

NCA parameter summary table in long format with individual records, stratified by covariate

R
initializeLixoftConnectors(software = "pkanalix")
loadProject(paste0(getDemoPath(),"/3.bioequivalence/project_crossover_foodeffect.pkx"))
runNCAEstimation()
tableNCAParameters(splitCovariates      = "FOOD",
                   splitCovariateLabels = "Food status",
                   selectParameters     = c("AUCINF_obs", "AUClast", "Cmax", "Cl_F_obs"),
                   metrics              = c("N", "min", "MeanSD","median", "max"),
                   useWideFormat        = FALSE, 
                   filterCovariates     = list(OCC = "1"),
                   filterIds            = c(1, 2, 3, 22, 23, 24),
                   includeIds           = TRUE,
                   aliases              = FALSE,
                   units                = FALSE,
                   prettyLabels         = FALSE)

#> Food status Statistic        AUCINF_obs           AUClast      Cl_F_obs          Cmax    Section
#>      Fasted         N                 3                 3             3             3    SUMMARY
#>      Fasted       min           479.843           411.483         0.828         6.812    SUMMARY
#>      Fasted    MeanSD 589.055 (124.258) 491.885 (115.241) 1.048 (0.212) 7.243 (0.482)    SUMMARY
#>      Fasted    median           563.072           440.259         1.066         7.153    SUMMARY
#>      Fasted       max           724.251           623.913         1.250         7.764    SUMMARY
#>      Fasted        22           563.072           440.259         1.066         7.153 INDIVIDUAL
#>      Fasted        23           479.843           411.483         1.250         6.812 INDIVIDUAL
#>      Fasted        24           724.251           623.913         0.828         7.764 INDIVIDUAL
#>         Fed         N                 3                 3             3             3    SUMMARY
#>         Fed       min           383.563           354.675         0.884         7.250    SUMMARY
#>         Fed    MeanSD 522.691 (148.273) 453.750 (104.291) 1.212 (0.341) 8.703 (2.208)    SUMMARY
#>         Fed    median           505.838           444.001         1.186         7.615    SUMMARY
#>         Fed       max           678.670           562.574         1.564        11.243    SUMMARY
#>         Fed         1           505.838           444.001         1.186         7.250 INDIVIDUAL
#>         Fed         2           678.670           562.574         0.884        11.243 INDIVIDUAL
#>         Fed         3           383.563           354.675         1.564         7.615 INDIVIDUAL

NCA parameter summary table in long format stratified by covariate (strata as columns)

R
initializeLixoftConnectors(software = "pkanalix")
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_units.pkx"))
runNCAEstimation()
tableNCAParameters(splitCovariates = "ROUTE",
                   stratifyColumns = TRUE,
                   useWideFormat   = FALSE,
                   roundDigits     = 2,
                   metrics         = c("N", "GeomCV"),
                   selectParameters = c("AUCINF_obs", "AUClast", "Cmax", "Tmax"))

#>                    Parameter              Statistic   ROUTE=IV\n(N=9) ROUTE=ORAL\n(N=9)   Overall\n(N=18)
#>  AUC[[sub:0-inf]] (h*ng/L)                      N                 9                 9                18
#>  AUC[[sub:0-inf]] (h*ng/L) Geometric\nMean (CV %) 254759.97 (11.69)  223960.69 (7.25) 238864.43 (11.55)
#>AUC[[sub:0-tlast]] (h*ng/L)                      N                 9                 9                18
#>AUC[[sub:0-tlast]] (h*ng/L) Geometric\nMean (CV %) 251853.32 (11.29)  221268.00 (6.92) 236065.84 (11.28)
#>        C[[sub:max]] (ng/L)                      N                 9                 9                18
#>        C[[sub:max]] (ng/L) Geometric\nMean (CV %)    4029.65 (9.85)   2614.03 (12.93)   3245.55 (25.28)
#>           T[[sub:max]] (h)                      N                 9                 9                18
#>           T[[sub:max]] (h) Geometric\nMean (CV %)     0.36 (228.86)     18.80 (48.88)    2.61 (1270.71)

NCA parameter summary table in long format stratified by covariate/occasion (strata as columns, mocked data)

R
loadProject(paste0(getDemoPath(),"/3.bioequivalence/project_crossover_foodeffect.pkx"))
runNCAEstimation()
tableNCAParameters(splitCovariates  = "OCC",
                   stratifyColumns  = TRUE, 
                   selectParameters = c("AUClast", "Cmax"),
                   metrics          = c("N", "min", "MeanSD","GeomCV", "median", "max"),
                   useWideFormat    = FALSE,
                   mock             = TRUE)

#>                    Parameter              Statistic OCC=Category 1\n(N=xx) OCC=Category 2\n(N=xx) Overall\n(N=xx)
#> AUC[[sub:0-tlast]] (h*mg/mL)                      N                 xx.xxx                 xx.xxx          xx.xxx
#> AUC[[sub:0-tlast]] (h*mg/mL)                Minimum                 xx.xxx                 xx.xxx          xx.xxx
#> AUC[[sub:0-tlast]] (h*mg/mL)  Arithmetic\nMean (SD)        xx.xxx (xx.xxx)        xx.xxx (xx.xxx) xx.xxx (xx.xxx)
#> AUC[[sub:0-tlast]] (h*mg/mL) Geometric\nMean (CV %)        xx.xxx (xx.xxx)        xx.xxx (xx.xxx) xx.xxx (xx.xxx)
#> AUC[[sub:0-tlast]] (h*mg/mL)                 Median                 xx.xxx                 xx.xxx          xx.xxx
#> AUC[[sub:0-tlast]] (h*mg/mL)                Maximum                 xx.xxx                 xx.xxx          xx.xxx
#>         C[[sub:max]] (mg/mL)                      N                 xx.xxx                 xx.xxx          xx.xxx
#>         C[[sub:max]] (mg/mL)                Minimum                 xx.xxx                 xx.xxx          xx.xxx
#>         C[[sub:max]] (mg/mL)  Arithmetic\nMean (SD)        xx.xxx (xx.xxx)        xx.xxx (xx.xxx) xx.xxx (xx.xxx)
#>         C[[sub:max]] (mg/mL) Geometric\nMean (CV %)        xx.xxx (xx.xxx)        xx.xxx (xx.xxx) xx.xxx (xx.xxx)
#>         C[[sub:max]] (mg/mL)                 Median                 xx.xxx                 xx.xxx          xx.xxx
#>         C[[sub:max]] (mg/mL)                Maximum                 xx.xxx                 xx.xxx          xx.xxx

NCA ratio summary table in wide format with custom parameter units

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_ivinfusion.pkx"))
runNCAEstimation()

tableNCAParameters(
  metrics = c("N", "min", "MeanSD", "median", "max"),
  customUnits = c(
    AUCINF_obs = "h*ng/mL",   
    AUClast    = "h*ng/mL",   
    Cl_obs     = "L/h",       
    Clast      = "ng/mL",     
    Cmax       = "ng/mL",     
    Lambda_z   = "1/h",       
    Tlast      = "h",         
    Tmax       = "h",         
    Vz_obs     = "L"          
  )
)

#>                    Parameter  N Minimum Arithmetic\nMean (SD) Median Maximum
#>   AUC[[sub:0-inf]] (h*ng/mL) 25  29.949       54.944 (20.357) 49.869 103.016
#> AUC[[sub:0-tlast]] (h*ng/mL) 25  26.532       46.370 (12.621) 42.580  73.440
#>                     CL (L/h) 25   0.485         1.016 (0.321)  1.003   1.670
#>        C[[sub:last]] (ng/mL) 25   0.158         0.645 (0.417)  0.523   1.666
#>         C[[sub:max]] (ng/mL) 25   2.843         4.390 (0.864)  4.385   6.330
#>           Flag_Lambda_z_Rule 25   1.000             1.000 (0)  1.000   1.000
#>            k[[sub:el]] (1/h) 25  0.0433       0.0977 (0.0273)  0.101   0.158
#>                    Intercept 25   1.102         1.726 (0.283)  1.767   2.147
#>             Number of points 25   3.000         4.160 (1.248)  4.000   6.000
#>                    R squared 25   0.944        0.992 (0.0125)  0.997   1.000
#>           adjusted R squared 25   0.930        0.989 (0.0161)  0.995   1.000
#>            T[[sub:last]] (h) 25  24.000            24.000 (0) 24.000  24.000
#>             T[[sub:max]] (h) 25   3.000         3.200 (0.408)  3.000   4.000
#>               V[[sub:d]] (L) 25   7.247        10.532 (2.417) 10.401  17.683

myUnits <- data.frame(
  parameter = c("AUCINF_obs", "AUClast", "Cl_obs", "Clast", "Cmax",
                "Lambda_z", "Tlast", "Tmax", "Vz_obs"),
  units     = c("h*ng/mL", "h*ng/mL", "L/h", "ng/mL", "ng/mL",
                "1/h", "h", "h", "L"),
  stringsAsFactors = FALSE
)

tableNCAParameters(
  metrics     = c("N", "min", "MeanSD", "median", "max"),
  customUnits = myUnits
)

#>                    Parameter  N Minimum Arithmetic\nMean (SD) Median Maximum
#>   AUC[[sub:0-inf]] (h*ng/mL) 25  29.949       54.944 (20.357) 49.869 103.016
#> AUC[[sub:0-tlast]] (h*ng/mL) 25  26.532       46.370 (12.621) 42.580  73.440
#>                     CL (L/h) 25   0.485         1.016 (0.321)  1.003   1.670
#>        C[[sub:last]] (ng/mL) 25   0.158         0.645 (0.417)  0.523   1.666
#>         C[[sub:max]] (ng/mL) 25   2.843         4.390 (0.864)  4.385   6.330
#>           Flag_Lambda_z_Rule 25   1.000             1.000 (0)  1.000   1.000
#>            k[[sub:el]] (1/h) 25  0.0433       0.0977 (0.0273)  0.101   0.158
#>                    Intercept 25   1.102         1.726 (0.283)  1.767   2.147
#>             Number of points 25   3.000         4.160 (1.248)  4.000   6.000
#>                    R squared 25   0.944        0.992 (0.0125)  0.997   1.000
#>           adjusted R squared 25   0.930        0.989 (0.0161)  0.995   1.000
#>            T[[sub:last]] (h) 25  24.000            24.000 (0) 24.000  24.000
#>             T[[sub:max]] (h) 25   3.000         3.200 (0.408)  3.000   4.000
#>               V[[sub:d]] (L) 25   7.247        10.532 (2.417) 10.401  17.683

Last updated: