MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableCategoricalCovariateSummary()

Builds a frequency table of the dataset's categorical covariates, reporting the count and percentage of subjects in each category. It can stratify by one or more categorical covariates (either as left-hand grouping columns or as a side-by-side layout with an Overall column), filter by covariate values or subject IDs, and apply custom display labels to both covariate names and their category values.

Usage

R
tableCategoricalCovariateSummary(projectFile           = NULL,
                                 covDisplayLabels      = NULL,
                                 categoryDisplayLabels = NULL,
                                 splitCovariates       = NULL,
                                 splitCovariateLabels  = NULL,
                                 stratifyColumns       = FALSE,
                                 filterCovariates      = NULL,
                                 filterIds             = NULL,
                                 roundDigits           = 2,
                                 roundMethod           = c("monolixSuiteRounding", "significantFigures", "significantFiguresPreserved", "none"),
                                 mock                  = FALSE)

Arguments

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

  • covDisplayLabels (data.frame): Optional mapping of dataset covariate names to display labels. Must have exactly the columns covariate and label. Covariates not listed keep their original names.

  • categoryDisplayLabels (data.frame): Optional mapping of category codes to display labels. Must have exactly the columns covariate, category, and label. Applied before covDisplayLabels (it keys on the original covariate names).

  • splitCovariates (character vector): Covariate name(s) to stratify by, e.g. "TREAT" or c("TREAT","FOOD"). If NULL (default), no stratification, overall summaries only. Occasion index columns (e.g. "AVISIT_OCC") may also be passed to resolve occasion-varying covariates.

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

  • filterCovariates (named list): Named list of categorical covariates → allowed values, e.g. list(SEX = "Male"). If NULL (default), no covariate filtering is applied.

  • filterIds (character or numeric vector): Subject IDs to include. If NULL (default), no ID filtering is applied.

  • roundDigits (numeric): Number of digits to display (default 2). Interpretation depends on roundMethod.

  • roundMethod (character): How numeric values are rounded:

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

  • mock (logical): When TRUE, masks the table for documentation and example outputs: data values become placeholders and real category codes become generic labels. Covariate names are kept. Default FALSE.

Examples

Categorical covariate summary table for all subjects

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

tableCategoricalCovariateSummary()

#> Subject characteristics Modalities Frequency\nN (%)
#>                   GROUP          1       10 (15.38)
#>                   GROUP          2       10 (15.38)
#>                   GROUP          3       10 (15.38)
#>                   GROUP          4       35 (53.85)
#>                     SEX          F       27 (41.54)
#>                     SEX          M       38 (58.46)

Categorical covariate summary table stratified by treatment group

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

tableCategoricalCovariateSummary(splitCovariates = "GROUP",
                                 stratifyColumns = TRUE)
)

#> Subject characteristics Modalities     GROUP=1     GROUP=2     GROUP=3    GROUP=4    Overall
#>                     SEX          M 10 (100.00) 10 (100.00)        <NA> 18 (51.43) 38 (58.46)
#>                     SEX          F        <NA>        <NA> 10 (100.00) 17 (48.57) 27 (41.54)

Categorical covariate summary table by covariate with custom labels

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

tableCategoricalCovariateSummary(
    splitCovariates       = "SEX",
    splitCovariateLabels  = "Sex",
    covDisplayLabels      = data.frame(covariate = "GROUP",
                                       label     = "Dose group"),
    categoryDisplayLabels = data.frame(
      covariate = "GROUP",
      category  = c("1", "2", "3", "4"),
      label     = c("Placebo", "Low", "Medium", "High"))
)

#> Sex Subject characteristics Modalities Frequency\nN (%)
#>   F              Dose group     Medium       10 (37.04)
#>   F              Dose group       High       17 (62.96)
#>   M              Dose group    Placebo       10 (26.32)
#>   M              Dose group        Low       10 (26.32)
#>   M              Dose group       High       18 (47.37)

Categorical covariate summary table filtered on selected covariate modalities

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

tableCategoricalCovariateSummary(
    filterCovariates = list(GROUP = c("1", "4")),
    roundDigits      = 1
)
#> Subject characteristics Modalities Frequency\nN (%)
#>                   GROUP          1        10 (22.2)
#>                   GROUP          4        35 (77.8)
#>                     SEX          F        17 (37.8)
#>                     SEX          M        28 (62.2)

Last updated: