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
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, orNULLto use the currently loaded project. -
covDisplayLabels(data.frame): Optional mapping of dataset covariate names to display labels. Must have exactly the columnscovariateandlabel. Covariates not listed keep their original names. -
categoryDisplayLabels(data.frame): Optional mapping of category codes to display labels. Must have exactly the columnscovariate,category, andlabel. Applied beforecovDisplayLabels(it keys on the original covariate names). -
splitCovariates(character vector): Covariate name(s) to stratify by, e.g."TREAT"orc("TREAT","FOOD"). IfNULL(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 forsplitCovariates. IfNULL(default), the original covariate names are used. Applied in both layouts: shown in the combined column headers whenstratifyColumns = TRUE, and used to rename the split-covariate columns whenstratifyColumns = FALSE. -
stratifyColumns(logical): IfTRUE, creates separate columns per covariate combination plus an "Overall" column. IfFALSE(default), covariates appear as left-side columns. Only applies whensplitCovariatesis set. -
filterCovariates(named list): Named list of categorical covariates → allowed values, e.g.list(SEX = "Male"). IfNULL(default), no covariate filtering is applied. -
filterIds(character or numeric vector): Subject IDs to include. IfNULL(default), no ID filtering is applied. -
roundDigits(numeric): Number of digits to display (default2). Interpretation depends onroundMethod. -
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 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.
-
-
mock(logical): WhenTRUE, masks the table for documentation and example outputs: data values become placeholders and real category codes become generic labels. Covariate names are kept. DefaultFALSE.
Examples
Categorical covariate summary table for all subjects
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
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
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
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)