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
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). IfNULL(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"orc("DOSE","VISIT"). IfNULL(default), no stratification. -
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. -
selectParameters(character) Ratio parameter names to include. IfNULL(default), all available ratio parameters are used. -
metrics(character) Summary statistics to include. IfNULL(default), all available metrics are included. Accepted values (returned bygetDescriptiveStatsMetrics(), 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), returns a wide table; ifFALSE, results are pivoted to long format. -
includeIds(logical) IfTRUE(withuseWideFormat = FALSEandstratifyColumns = FALSE), appends individual subject ratio values below the summary statistics. DefaultFALSE. -
filterCovariates(list) Named list of categorical covariates → allowed values, e.g.list(SEX = "Male"). IfNULL(default), no covariate filtering is applied. -
filterIds(character/numeric) 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.
-
-
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 (defaultNULL). -
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. -
prettyLabels(logical) IfTRUE(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 nounitsargument.) -
mock(logical) IfTRUE, masks values for documentation/examples (metric values become"xx.xx", covariate levels become"Category 1"…, IDs become"id1"…). DefaultFALSE.
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
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
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)
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
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
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)