Produces a subject-level listing of individual NCA ratio parameter values from a PKanalix project, one row per subject, with the selected (or all) ratio parameters as columns. Supports covariate stratification/sorting, covariate/ID filtering, per-parameter rounding, and custom aliases.
Usage
listingNCARatios(projectFile = NULL,
splitCovariates = NULL,
splitCovariateLabels = NULL,
selectParameters = NULL,
filterCovariates = NULL,
filterIds = NULL,
roundDigits = 3,
roundMethod = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
roundByParameter = NULL,
trailingZeros = TRUE,
aliases = TRUE,
customAliases = NULL,
mock = FALSE)
Arguments
-
projectFile(character) Path to a PKanalix project file (.pkx). IfNULL(default), uses the currently loaded project. -
splitCovariates(character vector) Categorical covariates (type"catcov") to include and sort by. If specified, the table is sorted by these covariates in the order provided, placed to the left ofid. Occasion-varying covariates are rejected, since ratios are computed across occasions and cannot be stratified by a within-subject-varying covariate. IfNULL(default), none are added (occasion-invariant stratification-only / additional-stratification categorical covariates defined in the project are still merged in automatically). -
splitCovariateLabels(character vector) Custom labels forsplitCovariates. IfNULL(default), the original covariate names are used. WhensplitCovariatesis set, these labels rename the corresponding covariate columns in the listing. -
selectParameters(character vector) Ratio parameters to include. IfNULL(default), all available ratio parameters are included. -
filterCovariates(list) Named list of categorical covariates → allowed values, e.g.list(SEX = "Male", DOSE = c("100","200")). Non-matching rows are dropped. 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.
-
-
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_ratio = 2, AUClast_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. -
aliases(logical) IfTRUE(default), parameter names are replaced with their aliases. -
customAliases(named character vector/ data.frame) Named vector or 2-column data frame mapping parameters → custom alias labels, e.g.c(Cmax_ratio = "C[[sub:max]] ratio"). Overrides project aliases. Supports[[sub:…]],[[sup:…]],~italic~. -
mock(logical) IfTRUE, masks values for documentation/examples:id→"id1", categorical / stratification covariates →"Category 1", and all numeric columns (continuous covariates, ratio parameter values) →"xx.xx". DefaultFALSE.
Return: A data frame with one row per subject, with the id column, splitCovariates (if specified, left of id) and the selected (or all) ratio parameter columns.
Examples
NCA ratio listing (default settings)
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
head(listingNCARatios())
#> id accumulationRatio DOSE_mg_kg_
#> 1 1.065 2
#> 2 1.455 2
#> 3 1.535 2
#> 4 1.250 2
#> 5 1.238 2
#> 6 1.630 2
NCA ratio listing split and sorted by covariate with custom aliases
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
head(listingNCARatios(
splitCovariates = "DOSE_mg_kg_",
customAliases = c(accumulationRatio = "AUC[[sub:τ]]/D (Day14 : Day1)")
)
)
#> DOSE_mg_kg_ id AUC[[sub:τ]]/D (Day14 : Day1)
#> 2 1 1.065
#> 2 2 1.455
#> 2 3 1.535
#> 2 4 1.250
#> 2 5 1.238
#> 2 6 1.630
NCA ratio listing filtered on covariate modalities and ids
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_accumulationRatio.pkx"))
runNCAEstimation()
listingNCARatios(
splitCovariates = "DOSE_mg_kg_",
splitCovariateLabels = "Dose (mg/kg)",
filterCovariates = list(DOSE_mg_kg_ = c("6","12")),
filterIds = c(9,10, 11, 17, 18, 19)
)
#> Dose (mg/kg) id accumulationRatio
#> 6 9 1.187
#> 6 10 1.289
#> 6 11 1.171
#> 12 17 1.102
#> 12 18 1.585
#> 12 19 1.221