This function summarizes the observations and subjects excluded from the analysis of a PKanalix or Monolix project, based on the exclusions identified by listingExclusions(). For each stratum it reports how many subjects and observations were excluded, together with per subject observation statistics, and the summary can be stratified and filtered. Unlike the other summary tables, stratification and filtering are not restricted to covariates: any column present in the dataset may be used, including columns tagged "ignore".
Usage
tableExclusions(projectFile = NULL,
splitCovariates = NULL,
splitCovariateLabels = NULL,
filterCovariates = NULL,
filterIds = NULL,
useWideFormat = TRUE,
maxSubjectRatio = 0.5,
prettyLabels = TRUE,
mock = FALSE)
Arguments
-
projectFile(character): Path to a PKanalix (.pkx) or Monolix (.mlxtran) project file, orNULLto use the currently loaded project. -
splitCovariates(character vector): Column(s) to stratify the summary by. Unlike the other tables this is not restricted to covariates: any column present in the dataset may be used, including columns tagged "ignore"; only non existent names are rejected. A warning is emitted if a chosen column has too many modalities per subject (seemaxSubjectRatio). IfNULL, an overall summary is provided. -
splitCovariateLabels(character vector): Custom labels forsplitCovariates, of the same length assplitCovariates; ifNULL(default), the original column names are used. WhensplitCovariatesis set, these labels rename the corresponding grouping columns in the table. -
filterCovariates(list): Named list where names are existing dataset columns (any column, not only covariates) and values are vectors of allowed values, e.g.list(VISIT = c("DAY 1", "DAY 7")). Rows not matching are dropped;NULLapplies no filtering. -
filterIds(character/numeric vector): Subject ids to include;NULLapplies no id filtering. -
useWideFormat(logical): WhenTRUE(default), the summary statistics are returned as columns (wide). WhenFALSE, the statistics are pivoted into rows (long,Statistic/Valueformat, useful for vertical reporting layouts). -
maxSubjectRatio(numeric): Ratio (number of modalities / number of subjects) above which a chosen grouping variable triggers a "might not be a suitable grouping variable" warning. Default0.5. -
prettyLabels(logical) IfTRUE(default), converts column names to report-ready labels (e.g."nbSbj"→"Nb. of Subjects"). -
mock(logical): WhenTRUE, masks the table for documentation and example outputs: the count and summary values become placeholders (e.g."xx.xx") and thesplitCovariatesgrouping values become generic labels ("Category 1", ...). DefaultFALSE.
Returns: A data frame summarizing the excluded observations and subjects. For each stratum (or overall when splitCovariates is NULL) it reports Nb. of Subjects, Total Nb. of Obs., Mean Nb. of Obs./Subject, Min. Nb. of Obs./Subject and Max. Nb. of Obs./Subject, preceded by the grouping columns when stratified. In wide format these statistics are columns; in long format they are pivoted into Statistic/Value rows. If the project has no exclusions, the function returns NULL invisibly (after listingExclusions() reports that no lines were filtered).
Examples
Summary table of excluded records
prj1 <- c("C:/Users/skollmann/Desktop/Work/Projects/2026/2026_Documentation/monolixSuiteTFL/listingExclusions/prj01_Exclusions.pkx")
loadProject(prj1)
tableExclusions(splitCovariates = c("Exclusion_reason"))
#> 11 lines were filtered in pkanalix
#> Nb. of Subjects Total Nb. of Obs. Mean Nb. of Obs./Subject Min. Nb. of Obs./Subject Max. Nb. of Obs./Subject
#> 9 11 1.22 1 3
Summary table of excluded records split by covariate
prj1 <- c("C:/Users/skollmann/Desktop/Work/Projects/2026/2026_Documentation/monolixSuiteTFL/listingExclusions/prj01_Exclusions.pkx")
loadProject(prj1)
tableExclusions(splitCovariates = c("Exclusion_reason"))
#> 11 lines were filtered in pkanalix
#> Exclusion_reason Nb. of Subjects Total Nb. of Obs. Mean Nb. of Obs./Subject Min. Nb. of Obs./Subject Max. Nb. of Obs./Subject
#> 1 Sample collected outside the protocol-defined window 2 3 1.5 1 2
#> 2 Documented bioanalytical or laboratory issue 3 3 1.0 1 1
#> 3 Documented sample handling or processing issue 3 3 1.0 1 1
#> 4 PK-inconsistent isolated value suggesting sample mix-up 2 2 1.0 1 1
Summary table of excluded records split and filtered by covariate in long format
prj1 <- c("C:/Users/skollmann/Desktop/Work/Projects/2026/2026_Documentation/monolixSuiteTFL/listingExclusions/prj01_Exclusions.pkx")
loadProject(prj1)
tableExclusions(splitCovariates = c("Exclusion_reason"),
filterCovariates = list(VISIT = c("DAY 1", "DAY 7")),
useWideFormat = FALSE)
#> 11 lines were filtered in pkanalix11 lines were filtered in pkanalix
#> Exclusion_reason Statistic Value
#> 1 Sample collected outside the protocol-defined window Nb. of Subjects 2
#> 1 Sample collected outside the protocol-defined window Total Nb. of Obs. 2
#> 1 Sample collected outside the protocol-defined window Mean Nb. of Obs./Subject 1
#> 1 Sample collected outside the protocol-defined window Min. Nb. of Obs./Subject 1
#> 1 Sample collected outside the protocol-defined window Max. Nb. of Obs./Subject 1
#> 2 Documented bioanalytical or laboratory issue Nb. of Subjects 1
#> 2 Documented bioanalytical or laboratory issue Total Nb. of Obs. 1
#> 2 Documented bioanalytical or laboratory issue Mean Nb. of Obs./Subject 1
#> 2 Documented bioanalytical or laboratory issue Min. Nb. of Obs./Subject 1
#> 2 Documented bioanalytical or laboratory issue Max. Nb. of Obs./Subject 1
#> 3 Documented sample handling or processing issue Nb. of Subjects 3
#> 3 Documented sample handling or processing issue Total Nb. of Obs. 3
#> 3 Documented sample handling or processing issue Mean Nb. of Obs./Subject 1
#> 3 Documented sample handling or processing issue Min. Nb. of Obs./Subject 1
#> 3 Documented sample handling or processing issue Max. Nb. of Obs./Subject 1
#> 4 PK-inconsistent isolated value suggesting sample mix-up Nb. of Subjects 2
#> 4 PK-inconsistent isolated value suggesting sample mix-up Total Nb. of Obs. 2
#> 4 PK-inconsistent isolated value suggesting sample mix-up Mean Nb. of Obs./Subject 1
#> 4 PK-inconsistent isolated value suggesting sample mix-up Min. Nb. of Obs./Subject 1
#> 4 PK-inconsistent isolated value suggesting sample mix-up Max. Nb. of Obs./Subject 1
Summary table of excluded records split by covariate (grouping suitability check)
prj1 <- c("C:/Users/skollmann/Desktop/Work/Projects/2026/2026_Documentation/monolixSuiteTFL/listingExclusions/prj01_Exclusions.pkx")
loadProject(prj1)
tableExclusions(
splitCovariates = "Exclusion_reason",
maxSubjectRatio = 0.1)
#> 11 lines were filtered in pkanalix
#> Exclusion_reason Nb. of Subjects Total Nb. of Obs. Mean Nb. of Obs./Subject Min. Nb. of Obs./Subject Max. Nb. of Obs./Subject
#> 1 Sample collected outside the protocol-defined window 2 3 1.5 1 2
#> 2 Documented bioanalytical or laboratory issue 3 3 1.0 1 1
#> 3 Documented sample handling or processing issue 3 3 1.0 1 1
#> 4 PK-inconsistent isolated value suggesting sample mix-up 2 2 1.0 1 1
#> Warning message:
#> Grouping variable 'Exclusion_reason' has 5 distinct values across 24 subjects (21% of subjects); it might not be a suitable grouping variable.