MonolixSuite in R
Auto Light Dark
Auto Light Dark

listingNCAParameters()

Produces a subject-level listing of individual NCA parameter values from a PKanalix project, one row per subject, with the selected (or all) NCA parameters as columns. Supports covariate stratification/sorting, covariate/ID filtering, per-parameter rounding, and (custom) aliases/units.

Usage

R
listingNCAParameters(projectFile          = NULL,
                     splitCovariates      = NULL,
                     splitCovariateLabels = NULL,
                     selectParameters     = NULL,
                     filterCovariates     = NULL,
                     filterIds            = NULL,
                     roundDigits          = 3,
                     roundMethod          = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                     roundByParameter     = NULL,
                     trailingZeros        = TRUE,
                     units                = TRUE,
                     aliases              = TRUE,
                     customUnits          = NULL,
                     customAliases        = NULL,
                     mock                 = FALSE)

Arguments

  • projectFile (character) Path to a PKanalix project file (.pkx). If NULL (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 of id. If NULL (default), none are added (stratification-only / additional-stratification categorical covariates defined in the project are still merged in automatically).

  • 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.

  • selectParameters (character vector) NCA parameters to include. If NULL (default), all computed NCA 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. 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.

  • 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 = 2, AUClast = 4)) or a 3-column data frame (parameter, digits, method). Unlisted parameters keep global settings (default NULL).

  • 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), parameter units are added to column names.

  • aliases (logical) If TRUE (default), parameter names are replaced with their aliases.

  • customUnits (named character vector/ data.frame) Named vector or 2-column data frame mapping parameters → custom unit labels, e.g. c(Cmax = "ng/mL", AUClast = "h*ng/mL"). Overrides units from the PKanalix project.

  • customAliases (named character vector/ data.frame) Named vector or 2-column data frame mapping parameters → custom alias labels, e.g. c(Cmax = "C[[sub:max]]", AUClast = "AUC[[sub:0-tlast]]"). Overrides project aliases. Supports [[sub:…]], [[sup:…]], ~italic~.

  • mock (logical) If TRUE, masks values for documentation/examples: id → "id1", occasions → "occ1", categorical / stratification covariates → "Category 1", and all numeric columns (continuous covariates, NCA parameter values) → "xx.xx". Default FALSE.

Returns: A data frame with one row per subject, containing the id column, the splitCovariates (if specified, placed to the left of id), any stratification-only / additional-stratification categorical covariates (merged in automatically when defined in the project), and the selected (or all) NCA parameter columns, with names formatted per units/aliases.

Examples

NCA parameter listing with selected parameters

R
loadProject(paste0(getDemoPath(), "/1.basic_examples/project_covariates.pkx"))
runNCAEstimation()
head(
  listingNCAParameters(
    selectParameters = c("AUCINF_obs", "AUClast", "Cmax", "Cl_F_obs", "Tmax"))
)

#>  id SEX   WEIGHT AUC[[sub:0-inf]] AUC[[sub:0-tlast]] C[[sub:max]]  CL/F T[[sub:max]]
#>   1   F 70.64658          229.041            195.763       21.521 0.437        1.500
#>   2   F 67.52091          206.242            203.308       38.935 0.485        2.000
#>   3   M 65.31013          101.088             71.658        5.343 0.989        3.000
#>   4   M 66.67008          104.046             97.229       10.928 0.961        1.500
#>   5   F 68.13107          167.318            155.305       15.226 0.598        2.000
#>   6   F 71.18658          274.589            212.016       20.334 0.364        5.000

NCA parameter listing with custom units

R
loadProject(paste0(getDemoPath(), "/1.basic_examples/project_covariates.pkx"))
runNCAEstimation()
myUnits <- data.frame(
  parameter = c("AUCINF_obs", "AUClast",  "Cmax",  "Cl_F_obs", "Tmax"),
  units     = c("h*mg/mL",    "h*mg/mL",  "mg/mL", "L/h",      "h"),
  stringsAsFactors = FALSE
)

head(
  listingNCAParameters(
    selectParameters = c("AUCINF_obs", "AUClast", "Cmax", "Cl_F_obs", "Tmax"),
    customUnits      = myUnits)
)

#> id SEX   WEIGHT AUC[[sub:0-inf]] (h*ng/mL) AUC[[sub:0-tlast]] (h*ng/mL) C[[sub:max]] (ng/mL)  CL/F T[[sub:max]] (h)
#>  1   F 70.64658                    229.041                      195.763               21.521 0.437            1.500
#>  2   F 67.52091                    206.242                      203.308               38.935 0.485            2.000
#>  3   M 65.31013                    101.088                       71.658                5.343 0.989            3.000
#>  4   M 66.67008                    104.046                       97.229               10.928 0.961            1.500
#>  5   F 68.13107                    167.318                      155.305               15.226 0.598            2.000
#>  6   F 71.18658                    274.589                      212.016               20.334 0.364            5.000

head(
  listingNCAParameters(
    selectParameters = c("AUCINF_obs", "AUClast", "Cmax", "Cl_F_obs", "Tmax"),
    customUnits      = c(AUCINF_obs = "h*mg/mL",
                         AUClast    = "h*mg/mL",
                         Cmax       = "mg/mL",
                         Cl_F_obs   = "L/h",
                         Tmax       = "h")
    )
)
#> id SEX   WEIGHT AUC[[sub:0-inf]] (h*ng/mL) AUC[[sub:0-tlast]] (h*ng/mL) C[[sub:max]] (ng/mL)  CL/F T[[sub:max]] (h)
#>  1   F 70.64658                    229.041                      195.763               21.521 0.437            1.500
#>  2   F 67.52091                    206.242                      203.308               38.935 0.485            2.000
#>  3   M 65.31013                    101.088                       71.658                5.343 0.989            3.000
#>  4   M 66.67008                    104.046                       97.229               10.928 0.961            1.500
#>  5   F 68.13107                    167.318                      155.305               15.226 0.598            2.000
#>  6   F 71.18658                    274.589                      212.016               20.334 0.364            5.000

NCA parameter listing filtered on covariate modalities and ids with different rounding methods and precision

R
loadProject(paste0(getDemoPath(), "/1.basic_examples/project_covariates.pkx"))
runNCAEstimation()

roundAUC <- data.frame(
  parameter = c("AUCINF_obs",         "AUClast"),
  digits    = c(4,                     4),
  method    = c("significantFigures",  "significantFigures"),
  stringsAsFactors = FALSE
)

head(
  listingNCAParameters(
    selectParameters = c("AUCINF_obs", "AUClast", "Cmax", "Cl_F_obs", "Tmax"),
    filterCovariates = list(SEX = "F"),
    filterIds        = c(1, 2, 5, 6, 8),
    roundDigits      = 2,
    roundMethod      = "significantFiguresPreserved",
    roundByParameter = roundAUC
  )
)
#> id SEX   WEIGHT AUC[[sub:0-inf]] AUC[[sub:0-tlast]] C[[sub:max]] CL/F T[[sub:max]]
#>  1   F 70.64658            229.0              195.8           22 0.44          1.5
#>  2   F 67.52091            206.2              203.3           39 0.48          2.0
#>  5   F 68.13107            167.3              155.3           15 0.60          2.0
#>  6   F 71.18658            274.6              212.0           20 0.36          5.0

Last updated: