MonolixSuite in R
Auto Light Dark
Auto Light Dark

listingNCAConcentration()

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

R
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). If NULL (default), uses the currently loaded project.

  • splitCovariates (character vector) Covariate name(s) to include as stratification columns, e.g. c("TREAT","FOOD"). If NULL (default), no stratification. Occasion columns present in the project are appended automatically (and concatenated into the subject ID with sep = "#" to keep IDs unique).

  • splitCovariateLabels(character vector) Custom labels for splitCovariates. If NULL (default), the original covariate names are used. When splitCovariates is set, these labels rename the corresponding covariate columns in the listing.

  • useNominalTime (logical) If TRUE, 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 is FALSE. (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. 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 columns and the concentration unit to both concentration columns.

  • 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: id → "id1", categorical covariates / occasions → "Category 1" / "occ1", and all numeric columns (time, Concentration, UsedConc, Censoring) → "xx.xx". Default FALSE.

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

R
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

R
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

R
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)

R
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

Last updated: