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
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). IfNULL(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"). IfNULL(default), no stratification — overall summaries only. -
splitCovariateLabels(character vector) Custom labels forsplitCovariates. IfNULL(default), the original covariate names are used. Applied in both layouts: shown in the combined column headers whenstratifyColumns = TRUE, and used to rename the split-covariate columns whenstratifyColumns = FALSE. -
stratifyColumns(logical) IfTRUE, creates separate columns per covariate combination plus an "Overall" column. IfFALSE(default), covariates appear as left-side columns. Only applies whensplitCovariatesis set anduseWideFormat = FALSE. -
useNominalTime(logical) IfTRUE(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) IfTRUE(default), time points are columns and statistics are rows (Statistic | [Covariates] | Time_0 | Time_1 | …). IfFALSE, time points are rows and statistics are columns (Time | [Covariates] | mean | SD | …).stratifyColumns = TRUErequiresFALSE. -
maxTimeDeviation(numeric) Maximum allowed percentage deviation between actual and nominal time. IfNULL(default), no filtering. When set (e.g.20for 20%), observations exceeding the threshold are excluded from summary statistics (NominalTime = 0is always kept). Only applies whenuseNominalTime = TRUE; individual data (includeIds = TRUE) is unaffected. -
includeIds(logical) IfTRUE, appends individual subject IDs and their concentrations at each time point below the summary statistics, grouped by covariate when stratified. DefaultFALSE. Only applies whenstratifyColumns = FALSE. -
filterCovariates(list) Named list of categorical covariates → allowed values, e.g.list(SEX = "Male"). IfNULL(default), no covariate filtering is applied. -
filterIds(character/numeric vector) Subject IDs to include. IfNULL(default), no ID filtering is applied. -
roundDigits(integer) Number of decimal places for rounding (default3). -
roundMethod(character) How numeric values are rounded.roundDigitscontrols 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 toroundDigitssignificant figures. Small values (< 1) automatically get more decimal places. -
"significantFigures"- Standard significant-figures rounding: the value is rounded toroundDigitstotal 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 leastroundDigitsdigits, 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 whenroundMethod != "none". IfTRUE(default), rounded concentration values are shown to the full precision implied byroundDigits/roundMethod, padding with trailing zeros (e.g.1.20,0.010); ifFALSE, the minimal form is shown. WithroundMethod = "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) IfTRUE(default), converts column names to report-ready labels (e.g."CV"→"CV (%)"). -
mock(logical) IfTRUE, masks values for documentation/examples (statistic values become"xx.xx", covariate levels become"Category 1"…, IDs become"id1"…). Time headers andStatistic/Sectionlabels are kept. DefaultFALSE.
Examples
NCA concentration summary table in wide format
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
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)
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)
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