MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableNCARatios()

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

Usage

R
tableNCARatios(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,
               prettyLabels         = TRUE,
               customAliases        = NULL,
               mock                 = FALSE)

Arguments

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

  • splitCovariates (character) Column name(s) to stratify by (must exist in the individual-ratio data, excluding id/ratio columns), e.g. "DOSE" or c("DOSE","VISIT"). If NULL (default), no stratification.

  • 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) Ratio parameter names to include. If NULL (default), all available ratio parameters are used.

  • metrics (character) 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; if FALSE, results are pivoted to long format.

  • includeIds(logical) If TRUE (with useWideFormat = FALSE and stratifyColumns = FALSE), appends individual subject ratio values below the summary statistics. Default FALSE.

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

  • filterIds (character/numeric) 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 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.

  • roundByParameter (named numeric vector/ data.frame) Per-parameter rounding overrides on top of the global settings, either a named numeric vector of digits (c(AUClast_ratio = 2, Cmax_ratio = 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), converts column names to report-ready labels.

  • customAliases (named character vector/ data.frame) Named vector or 2-column data frame mapping parameters → custom alias labels. (Ratios are dimensionless, so there is no units argument.)

  • 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 of summary statistics (N, Min, Q1, Mean, Median, Q3, Max) for each ratio parameter, optionally stratified; when includeIds= TRUE, also individual per-subject ratio values.

Examples

NCA ratio summary table in wide format

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
tableNCARatios(metrics = c("N", "min", "MeanSD","median", "max"))

#>         Parameter  N Minimum Arithmetic\nMean (SD) Median Maximum
#> accumulationRatio 24   1.011         1.261 (0.165)  1.219   1.630

NCA ratio summary table in long format stratified by covariate

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
tableNCARatios(splitCovariates = "DOSE_mg_kg_",
               metrics         = c("N", "min", "MeanSD","median", "max"),
               useWideFormat   = FALSE)

#> DOSE_mg_kg_             Statistic accumulationRatio
#>           2                     N                 8
#>           2               Minimum             1.065
#>           2 Arithmetic\nMean (SD)     1.331 (0.195)
#>           2                Median             1.287
#>           2               Maximum             1.630
#>           6                     N                 8
#>           6               Minimum             1.072
#>           6 Arithmetic\nMean (SD)    1.219 (0.0825)
#>           6                Median             1.210
#>           6               Maximum             1.341
#>          12                     N                 8
#>          12               Minimum             1.011
#>          12 Arithmetic\nMean (SD)     1.232 (0.190)
#>          12                Median             1.172
#>          12               Maximum             1.585

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

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
tableNCARatios(splitCovariates = "DOSE_mg_kg_",
               stratifyColumns = TRUE,
               metrics         = c("N", "min", "MeanSD","median", "max"),
               useWideFormat   = FALSE)

#>         Parameter             Statistic DOSE_mg_kg_=2\n(N=8) DOSE_mg_kg_=6\n(N=8) DOSE_mg_kg_=12\n(N=8) Overall\n(N=24)
#> accumulationRatio                     N                    8                    8                     8              24
#> accumulationRatio               Minimum                1.065                1.072                 1.011           1.011
#> accumulationRatio Arithmetic\nMean (SD)        1.331 (0.195)       1.219 (0.0825)         1.232 (0.190)   1.261 (0.165)
#> accumulationRatio                Median                1.287                1.210                 1.172           1.219
#> accumulationRatio               Maximum                1.630                1.341                 1.585           1.630

NCA ratio summary table in long format split by covariate, filtered by covariate and Ids

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

tableNCARatios(splitCovariates  = "DOSE_mg_kg_",
               metrics          = c("N", "min", "MeanSD","median", "max"),
               useWideFormat    = FALSE,
               filterCovariates = list(DOSE_mg_kg_ = "2"),
               includeIds       = TRUE,
               filterIds        = c(1, 2, 3, 4, 5, 6))

#> DOSE_mg_kg_             Statistic accumulationRatio    Section
#>           2                     N                 6    SUMMARY
#>           2               Minimum             1.065    SUMMARY
#>           2 Arithmetic\nMean (SD)     1.362 (0.213)    SUMMARY
#>           2                Median             1.353    SUMMARY
#>           2               Maximum             1.630    SUMMARY
#>           2                     1             1.065 INDIVIDUAL
#>           2                     2             1.455 INDIVIDUAL
#>           2                     3             1.535 INDIVIDUAL
#>           2                     4             1.250 INDIVIDUAL
#>           2                     5             1.238 INDIVIDUAL
#>           2                     6             1.630 INDIVIDUAL

NCA ratio summary table in wide format with custom parameter aliases

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
tableNCARatios(
  metrics       = "MeanSD",
  customAliases = c(accumulationRatio = "AUC[[sub:τ]]/D (Day14 : Day1)")
)
#>                     Parameter Arithmetic\nMean (SD)
#> AUC[[sub:τ]]/D (Day14 : Day1)         1.261 (0.165)

myAliases <- data.frame(
  parameter = c("accumulationRatio"),
  aliases   = c("AUC[[sub:τ]]/D (Day14) / AUC[[sub:τ]]/D (Day1)"),
  stringsAsFactors = FALSE
)
tableNCARatios(
  metrics       = "MeanSD",
  customAliases = myAliases
)
#>                                      Parameter Arithmetic\nMean (SD)
#> AUC[[sub:τ]]/D (Day14) / AUC[[sub:τ]]/D (Day1)         1.261 (0.165)

Last updated: