Produces a long-format subject-level listing of individual NCA concentrations by time from a PKanalix project, one row per subject/time point, joined with the used-concentration data (which points entered the lambda-z calculation) and censoring flags. Supports stratification/occasion columns, optional nominal time, and covariate/ID filtering.
Usage
listingNCAConcentration(projectFile = NULL,
splitCovariates = NULL,
splitCovariateLabels = NULL,
useNominalTime = FALSE,
filterCovariates = NULL,
filterIds = NULL,
roundDigits = 3,
roundMethod = c("none", "monolixSuiteRounding", "significantFigures", "significantFiguresPreserved"),
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. -
splitCovariates(character vector) Covariate name(s) to include as stratification columns, e.g.c("TREAT","FOOD"). IfNULL(default), no stratification. Occasion columns present in the project are appended automatically (and concatenated into the subject ID withsep = "#"to keep IDs unique). -
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. -
useNominalTime(logical) IfTRUE, attempts to use nominal time for the listing; if nominal time is unavailable in the project, falls back to actual time and issues a warning. Default isFALSE. (Actual time is always extracted so the listing can join with the lambda-z point data.) -
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.
-
-
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) IfTRUE(default) and units are enabled in the project, appends the time unit to the time columns and the concentration unit to both concentration columns. -
prettyLabels(logical) IfTRUE(default), converts column names to report-ready labels (e.g."CV"→"CV (%)"). -
mock(logical) IfTRUE, masks values for documentation/examples:id→"id1", categorical covariates / occasions →"Category 1"/"occ1", and all numeric columns (time,Concentration,UsedConc,Censoring) →"xx.xx". DefaultFALSE.
Return: A data frame in long format, one row per concentration record, with (if present) splitCovariates, id, ActualTime, NominalTime, Concentration, UsedConc, and Censoring. Fixed columns are shown with pretty labels and units by defaul.
Examples
NCA concentration listing by nominal sampling time, grouped by SEX
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
head(
listingNCAConcentration(
splitCovariates = "SEX",
useNominalTime = TRUE)
)
#> SEX id Actual Time (h) Nominal Time (h) Concentration (mg/L) Used Concentration (mg/L) Censoring
#> F 5 0.30 0.25 2.020 2.020 0
#> F 5 0.52 0.50 5.630 5.630 0
#> F 5 1.00 1.00 11.400 11.400 0
#> F 5 2.02 2.00 9.330 9.330 0
#> F 5 3.50 3.50 8.740 8.740 0
#> F 5 5.02 5.00 7.560 7.560 0
NCA concentration listing selected female subjects, with a relabeled covariate column
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
head(
listingNCAConcentration(
splitCovariates = "SEX",
splitCovariateLabels = "Sex",
filterCovariates = list(SEX = "F"),
filterIds = c(1, 2, 5))
)
#> Sex id Actual Time (h) Concentration (mg/L) Used Concentration (mg/L) Censoring
#> F 5 0.30 2.020 2.020 0
#> F 5 0.52 5.630 5.630 0
#> F 5 1.00 11.400 11.400 0
#> F 5 2.02 9.330 9.330 0
#> F 5 3.50 8.740 8.740 0
#> F 5 5.02 7.560 7.560 0
NCA concentration listing with significant-figure rounding and no units
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
head(listingNCAConcentration(
units = FALSE,
roundDigits = 3,
roundMethod = "significantFigures",
trailingZeros = FALSE)
)
#> id Actual Time Concentration Used Concentration Censoring
#> 1 0.25 2.84 2.84 0
#> 1 0.57 6.57 6.57 0
#> 1 1.12 10.5 10.5 0
#> 1 2.02 9.66 9.66 0
#> 1 3.82 8.58 8.58 0
#> 1 5.10 8.36 8.36 0
NCA concentration listing masked for sharing (mock mode)
loadProject(paste0(getDemoPath(),"/1.basic_examples/project_nominal_time.pkx"))
runNCAEstimation()
head(
listingNCAConcentration(
splitCovariates = "SEX",
splitCovariateLabels = "Sex",
filterCovariates = list(SEX = "F"),
filterIds = c(1, 2, 5),
mock = TRUE)
)
#> Sex id Actual Time (h) Concentration (mg/L) Used Concentration (mg/L) Censoring
#> Category 1 id1 xx.xxx xx.xxx xx.xxx xx.xxx
#> Category 1 id1 xx.xxx xx.xxx xx.xxx xx.xxx
#> Category 1 id1 xx.xxx xx.xxx xx.xxx xx.xxx
#> Category 1 id1 xx.xxx xx.xxx xx.xxx xx.xxx
#> Category 1 id1 xx.xxx xx.xxx xx.xxx xx.xxx
#> Category 1 id1 xx.xxx xx.xxx xx.xxx xx.xxx