MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableContinuousCovariateSummary()

This function generates a report ready summary table of the continuous covariates in a Monolix or PKanalix dataset, described with descriptive statistics.

Usage

R
tableContinuousCovariateSummary(projectFile          = NULL,
                                splitCovariates      = NULL,
                                splitCovariateLabels = NULL,
                                stratifyColumns      = FALSE,
                                metrics              = NULL,
                                useWideFormat        = TRUE,
                                filterCovariates     = NULL,
                                filterIds            = NULL,
                                roundDigits          = 2,
                                roundMethod          = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                                trailingZeros        = TRUE,
                                customUnits          = NULL,
                                customAliases        = NULL,
                                prettyLabels         = TRUE,
                                mock                 = FALSE)

Arguments

  • projectFile (character): Path to a Monolix (.mlxtran) or PKanalix (.pkx) project file, or NULL to use the currently loaded project.

  • splitCovariates (character vector) Covariate name(s) to stratify by, e.g. "TREAT" or c("TREAT","FOOD"). If NULL (default), no stratification - overall summaries only.

  • splitCovariateLabels (character vector) Custom labels for splitCovariates. If NULL (default), the original covariate names are used. Applied in both layouts: shown in the combined column headers when stratifyColumns = TRUE, and used to rename the split-covariate columns when stratifyColumns = FALSE.

  • stratifyColumns (logical) If TRUE, creates separate columns per covariate combination plus an "Overall" column. If FALSE (default), covariates appear as left-side columns. Only applies when splitCovariates is set and useWideFormat = FALSE.

  • metrics (character vector): Summary statistics to display, or NULL to display all available metrics. The accepted names come from getDescriptiveStatsMetrics():

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

  • The per group geoSD/geoCV (raw geometric statistics) are distinct from the combined display metrics GeomSD/GeomCV/MeanSD/MeanCV, which format a central value together with its dispersion in a single cell (e.g. MeanSD reads as "70.00 (12.30)").

  • useWideFormat (logical) If TRUE (default), returns a wide table with one row per covariate level. If FALSE, returns a vertical table with Statistic as the first column. Note: stratifyColumns = TRUE is only compatible with useWideFormat = FALSE

  • filterCovariates (list) Named list of categorical covariates → allowed values, e.g. list(SEX = "Male"). 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 digits to display (default 2).

  • roundMethod (character): Rounding approach.

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

  • customUnits (named vector or 2 column data frame): Maps dataset covariate names to custom unit labels, e.g. c(WEIGHT = "kg", HEIGHT = "cm"). Units are appended in parentheses, for example "Weight (kg)".

  • customAliases (named vector or 2 column data frame): Maps dataset covariate names to custom display labels, e.g. c(WEIGHT = "Weight", AGE = "Age"). Covariates not in the mapping keep their original names.

  • prettyLabels (logical): When TRUE (default), converts column names to human readable labels (e.g. "CV" becomes "CV (%)", "geoMean" becomes "Geometric Mean").

  • mock (logical): When TRUE, masks the table for documentation and example outputs: data values become placeholders (e.g. "xx.xx") and the real category codes of splitCovariates become generic labels ("Category 1", ...). Covariate names and statistic labels are kept. Default FALSE.

Examples

Continuous covariate summary table in wide format with selected metrics

R
initializeLixoftConnectors(path.software, software = "pkanalix")
loadProject(paste0(getDemoPath(),"/2.case_studies/project_Theo_extravasc_SD.pkx"))
getDescriptiveStatsMetrics()
tableContinuousCovariateSummary(
  metrics = c("N",  "min", "Q1", "median", "MeanSD", "GeomCV", "Q3", "max")
)

#> Covariate  N Minimum     Q1 Median Arithmetic\nMean (SD) Geometric\nMean (CV %)     Q3 Maximum
#>      AGE 18   21.00  22.00  25.00          26.22 (5.07)          25.81 (17.85)  28.00   39.00
#>       HT 18  176.00 179.00 181.00         181.72 (4.32)          181.67 (2.36) 183.00  191.00
#>       WT 18   65.00  68.00  70.00          71.78 (5.34)           71.60 (7.30)  77.00   83.00

Continuous covariate summary table in long format, split and filtered by covariate

R
initializeLixoftConnectors(path.software, software = "pkanalix")
loadProject(paste0(getDemoPath(),"/2.case_studies/project_Theo_extravasc_SD.pkx"))
tableContinuousCovariateSummary(
  splitCovariates      = "FORM",
  splitCovariateLabels = "Treatment",
  filterCovariates     = list(Period = c("1")),
  useWideFormat        = FALSE,
  metrics              = c("N",  "min", "Q1", "median", "MeanSD", "GeomCV", "Q3", "max")
)

#> Treatment              Statistic           AGE            HT           WT
#>       ref                      N             9             9            9
#>       ref                Minimum         21.00        176.00        65.00
#>       ref                     Q1         22.00        179.25        66.75
#>       ref                 Median         25.00        181.00        68.00
#>       ref  Arithmetic\nMean (SD)  27.11 (6.74) 181.44 (4.10) 69.11 (3.79)
#>       ref Geometric\nMean (CV %) 26.44 (23.51) 181.40 (2.24) 69.02 (5.31)
#>       ref                     Q3         31.00        183.00        70.00
#>       ref                Maximum         39.00        190.00        78.00
#>      test                      N             9             9            9
#>      test                Minimum         22.00        177.00        67.00
#>      test                     Q1         22.75        178.50        69.50
#>      test                 Median         25.00        181.00        74.00
#>      test  Arithmetic\nMean (SD)  25.33 (2.74) 182.00 (4.77) 74.44 (5.50)
#>      test Geometric\nMean (CV %) 25.20 (10.79) 181.95 (2.60) 74.26 (7.41)
#>      test                     Q3         27.25        186.00        78.50
#>      test                Maximum         30.00        191.00        83.00

Continuous covariate summary in long format, stratified by occasion (strata as columns) with custom aliases and units (mocked values)

R
initializeLixoftConnectors(path.software, software = "pkanalix")
loadProject(paste0(getDemoPath(),"/2.case_studies/project_Theo_extravasc_SD.pkx"))

tableContinuousCovariateSummary(
  splitCovariates      = c("Period"),
  splitCovariateLabels = "Study period",
  stratifyColumns      = TRUE,
  metrics              = c("N",  "min", "Q1", "median", "MeanSD", "GeomCV", "Q3", "max"),
  useWideFormat        = FALSE,
  customAliases        = c(WT = "Weight", HT = "Height", AGE = "Age"),
  customUnits          = c(WT = "kg",     HT = "cm",     AGE = "years"),
  mock                 = TRUE
)

#>   Covariate              Statistic Study period=Category 1\n(N=xx) Study period=Category 2\n(N=xx) Overall\n(N=xx)
#> Age (years)                      N                           xx.xx                           xx.xx           xx.xx
#> Age (years)                Minimum                           xx.xx                           xx.xx           xx.xx
#> Age (years)                     Q1                           xx.xx                           xx.xx           xx.xx
#> Age (years)                 Median                           xx.xx                           xx.xx           xx.xx
#> Age (years)  Arithmetic\nMean (SD)                   xx.xx (xx.xx)                   xx.xx (xx.xx)   xx.xx (xx.xx)
#> Age (years) Geometric\nMean (CV %)                   xx.xx (xx.xx)                   xx.xx (xx.xx)   xx.xx (xx.xx)
#> Age (years)                     Q3                           xx.xx                           xx.xx           xx.xx
#> Age (years)                Maximum                           xx.xx                           xx.xx           xx.xx
#> Height (cm)                      N                           xx.xx                           xx.xx           xx.xx
#> Height (cm)                Minimum                           xx.xx                           xx.xx           xx.xx
#> Height (cm)                     Q1                           xx.xx                           xx.xx           xx.xx
#> Height (cm)                 Median                           xx.xx                           xx.xx           xx.xx
#> Height (cm)  Arithmetic\nMean (SD)                   xx.xx (xx.xx)                   xx.xx (xx.xx)   xx.xx (xx.xx)
#> Height (cm) Geometric\nMean (CV %)                   xx.xx (xx.xx)                   xx.xx (xx.xx)   xx.xx (xx.xx)
#> Height (cm)                     Q3                           xx.xx                           xx.xx           xx.xx
#> Height (cm)                Maximum                           xx.xx                           xx.xx           xx.xx
#> Weight (kg)                      N                           xx.xx                           xx.xx           xx.xx
#> Weight (kg)                Minimum                           xx.xx                           xx.xx           xx.xx
#> Weight (kg)                     Q1                           xx.xx                           xx.xx           xx.xx
#> Weight (kg)                 Median                           xx.xx                           xx.xx           xx.xx
#> Weight (kg)  Arithmetic\nMean (SD)                   xx.xx (xx.xx)                   xx.xx (xx.xx)   xx.xx (xx.xx)
#> Weight (kg) Geometric\nMean (CV %)                   xx.xx (xx.xx)                   xx.xx (xx.xx)   xx.xx (xx.xx)
#> Weight (kg)                     Q3                           xx.xx                           xx.xx           xx.xx
#> Weight (kg)                Maximum                           xx.xx                           xx.xx           xx.xx

Continuous covariate summary table split by covariate, filtered on ids, with significant figure rounding

R
initializeLixoftConnectors(path.software, software = "monolix")
loadProject(paste0(getDemoPath(),"/1.creating_and_using_models/1.1.libraries_of_models/warfarinPKPD_project.mlxtran"))

tableContinuousCovariateSummary(
  splitCovariates = "sex",
  metrics         = c("N",  "min", "median", "MeanSD", "GeomCV", "max"),
  filterIds       = c(1, 2, 3, 4, 5, 6),
  roundDigits     = 3,
  roundMethod     = "significantFigures",
  trailingZeros   = FALSE,
  prettyLabels    = FALSE
)

#> Covariate sex N  min median      MeanSD      GeomCV max
#>       age   0 2   36     41   41 (7.07) 40.7 (17.5)  46
#>       age   1 4   31   41.5   41 (7.87) 40.4 (20.2)  50
#>        wt   0 2   40     50   50 (14.1)   49 (29.3)  60
#>        wt   1 4 66.7     71 72.2 (6.61)   72 (9.11)  80

Last updated: