MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableNCAConcentration()

Returns a reporting-ready summary table of NCA concentration data over time from a PKanalix project. Transforms individual concentration profiles into summary statistics per time point, with optional stratification by covariates, wide or long layouts, nominal-time handling with deviation filtering, and optional inclusion of individual subject values.

Usage

R
tableNCAConcentration(projectFile          = NULL,
                      splitCovariates      = NULL,
                      splitCovariateLabels = NULL,
                      stratifyColumns      = FALSE,
                      useNominalTime       = TRUE,
                      metrics              = NULL,
                      useWideFormat        = TRUE,
                      maxTimeDeviation     = NULL,
                      includeIds           = FALSE,
                      filterCovariates     = NULL,
                      filterIds            = NULL,
                      roundDigits          = 3,
                      roundMethod          = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                      trailingZeros        = TRUE,
                      units                = TRUE,
                      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. c("DOSE","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.

  • useNominalTime (logical) If TRUE (default), uses nominal time for the summary table; if nominal time is unavailable in the project, falls back to actual time with a warning.

  • 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), time points are columns and statistics are rows (Statistic | [Covariates] | Time_0 | Time_1 | …). If FALSE, time points are rows and statistics are columns (Time | [Covariates] | mean | SD | …). stratifyColumns = TRUE requires FALSE.

  • maxTimeDeviation (numeric) Maximum allowed percentage deviation between actual and nominal time. If NULL (default), no filtering. When set (e.g. 20 for 20%), observations exceeding the threshold are excluded from summary statistics (NominalTime = 0 is always kept). Only applies when useNominalTime = TRUE; individual data (includeIds = TRUE) is unaffected.

  • includeIds (logical) If TRUE, appends individual subject IDs and their concentrations at each time point below the summary statistics, grouped by covariate when stratified. Default FALSE. Only applies when stratifyColumns = 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 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 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.

  • 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) and units are enabled in the project, appends the time unit to the time column header in the long layout (useWideFormat = FALSE), e.g. "Nominal time (d)". No effect in the wide layout.

  • 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 (statistic values become "xx.xx", covariate levels become "Category 1"…, IDs become "id1"…). Time headers and Statistic/Section labels are kept. Default FALSE.

Examples

NCA concentration summary table in wide format

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

tableNCAConcentration(metrics     = c("N","min", "Q1", "MeanSD", "GeomCV", "median", "Q3", "max"),
                      roundDigits = 3,
                      roundMethod = "significantFiguresPreserved")

#>             Statistic Time = 0.25  Time = 0.5    Time = 1    Time = 2  Time = 3.5    Time = 5    Time = 7    Time = 9   Time = 12    Time = 24
#>                     N          12          12          12          12          12          12          12          12          12           12
#>               Minimum       0.850        2.35        5.02        6.32        5.53        4.94        4.02        3.46        2.69        0.860
#>                    Q1        1.50        3.52        6.79        6.70        6.23        5.78        4.59        4.25        3.00        0.985
#> Arithmetic\nMean (SD) 2.87 (1.88) 5.46 (2.12) 7.93 (1.74) 7.89 (1.24) 7.49 (1.55) 6.77 (1.37) 5.70 (1.32) 5.08 (1.21) 3.88 (1.09) 1.40 (0.725)
#>Geometric\nMean (CV %) 2.39 (69.5) 5.05 (44.7) 7.76 (22.2) 7.80 (15.8) 7.35 (20.7) 6.64 (20.2) 5.56 (23.1) 4.95 (23.9) 3.76 (27.3)  1.28 (42.3)
#>                Median        2.43        5.42        7.91        7.82        7.30        6.43        5.35        4.74        3.62         1.15
#>                    Q3        3.72        7.07        8.46        8.86        8.66        7.96        6.84        6.01        4.47         1.41
#>               Maximum        7.37        9.03        11.4        9.72        10.2        9.18        8.02        7.14        5.94         3.28

NCA concentration summary table in long format using actual time

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
head(
  tableNCAConcentration(metrics        = c("N","min", "Q1", "MeanSD", "GeomCV", "median", "Q3", "max"),
                        useWideFormat  = FALSE,
                        useNominalTime = FALSE
                        )
  )

#>Actual Time (h) N Minimum    Q1 Arithmetic\nMean (SD) Geometric\nMean (CV %) Median    Q3 Maximum
#>           0.25 5   0.850 1.150         2.570 (1.601)         2.139 (81.055)  2.840 3.502   4.860
#>           0.27 3   1.290 1.398         2.470 (1.685)         2.137 (71.375)  1.720 3.730   4.400
#>           0.30 2   2.020 2.020         4.695 (3.783)        3.858 (114.494)  4.695 7.370   7.370
#>           0.35 1   1.890 1.890            1.890 (NA)             1.890 (NA)  1.890 1.890   1.890
#>           0.37 1   2.890 2.890            2.890 (NA)             2.890 (NA)  2.890 2.890   2.890
#>           0.50 3   2.350 2.753         4.517 (2.492)         4.069 (61.083)  3.960 6.420   7.240

NCA concentration summary table in long format stratified by covariate/occasion (strata as columns)

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
head(
  tableNCAConcentration(
    splitCovariates = "SEX",
    stratifyColumns = TRUE,
    metrics         = c("N", "GeomCV"),
    roundDigits     = 3,
    roundMethod     = "significantFiguresPreserved",
    useWideFormat   = FALSE
    )
  )

#>Nominal Time (h)              Statistic SEX=F\n(N=5) SEX=M\n(N=7) Overall\n(N=12)
#>            0.25                      N            5            7              12
#>            0.25 Geometric\nMean (CV %)  1.98 (77.4)  2.75 (65.4)     2.39 (69.5)
#>            0.50                      N            5            7              12
#>            0.50 Geometric\nMean (CV %)  4.56 (44.9)  5.43 (46.5)     5.05 (44.7)
#>            1.00                      N            5            7              12
#>            1.00 Geometric\nMean (CV %)  7.45 (31.0)  7.98 (15.9)     7.76 (22.2)

NCA concentration summary table in long format with individual records, stratified and filtered by covariate (excluding observations with >15% deviation from nominal sampling time)

R
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
tableNCAConcentration(
  splitCovariates  = "SEX",
  metrics          = c("N","min", "Q1", "MeanSD", "GeomCV", "median", "Q3", "max"),
  includeIds       = TRUE,
  maxTimeDeviation = 15,
  filterCovariates = list(SEX = "F"),
  roundDigits      = 2
  ) 
#> Excluded 3 observations exceeding 0.15% time deviation threshold.
#> SEX              Statistic   Time = 0.25   Time = 0.5     Time = 1     Time = 2   Time = 3.5     Time = 5     Time = 7     Time = 9    Time = 12    Time = 24    Section
#>   F                      N             3            4            5            5            5            5            5            5            5            5    SUMMARY
#>   F                Minimum          0.85         2.35         5.02         6.58         5.87         5.22         4.45         3.62         2.69         0.86    SUMMARY
#>   F                     Q1          0.95         3.16         6.06         6.75         6.78         6.30         5.05         4.20         3.32         1.08    SUMMARY
#>   F  Arithmetic\nMean (SD)   2.32 (2.21)  4.80 (2.11)  7.73 (2.38)  8.05 (1.43)  8.33 (1.82)  7.44 (1.57)  6.28 (1.43)  5.43 (1.41)  4.17 (1.13)  1.43 (0.61)    SUMMARY
#>   F Geometric\nMean (CV %) 1.73 (114.61) 4.41 (51.81) 7.45 (30.99) 7.95 (17.89) 8.16 (23.49) 7.30 (22.66) 6.14 (24.07) 5.28 (27.97) 4.04 (28.91) 1.34 (40.69)    SUMMARY
#>   F                 Median          1.25         4.80         7.82         7.83         8.74         7.56         6.59         5.90         4.37         1.17    SUMMARY
#>   F                     Q3          3.96         6.44         8.85         9.43         9.87         8.72         7.32         6.37         4.85         1.78    SUMMARY
#>   F                Maximum          4.86         7.24        11.40         9.72        10.21         9.18         8.02         7.14         5.68         2.42    SUMMARY
#>   F                      5          2.02         5.63        11.40         9.33         8.74         7.56         7.09         5.90         4.37         1.57 INDIVIDUAL
#>   F                      7          0.85         2.35         5.02         6.58         7.09         6.66         5.25         4.39         3.53         1.15 INDIVIDUAL
#>   F                     10          2.89         5.22         6.41         7.83        10.21         9.18         8.02         7.14         5.68         2.42 INDIVIDUAL
#>   F                     11          4.86         7.24         8.00         6.81         5.87         5.22         4.45         3.62         2.69         0.86 INDIVIDUAL
#>   F                     12          1.25         3.96         7.82         9.72         9.75         8.57         6.59         6.11         4.57         1.17 INDIVIDUAL

Last updated: