MonolixSuite in R
Auto Light Dark
Auto Light Dark

tableExclusions()

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

R
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, or NULL to 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 (see maxSubjectRatio). If NULL, an overall summary is provided.

  • splitCovariateLabels (character vector): Custom labels for splitCovariates, of the same length as splitCovariates; if NULL (default), the original column names are used. When splitCovariates is 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; NULL applies no filtering.

  • filterIds (character/numeric vector): Subject ids to include; NULL applies no id filtering.

  • useWideFormat (logical): When TRUE (default), the summary statistics are returned as columns (wide). When FALSE, the statistics are pivoted into rows (long, Statistic/Value format, 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. Default 0.5.

  • prettyLabels (logical) If TRUE (default), converts column names to report-ready labels (e.g. "nbSbj" → "Nb. of Subjects").

  • mock (logical): When TRUE, masks the table for documentation and example outputs: the count and summary values become placeholders (e.g. "xx.xx") and the splitCovariates grouping values become generic labels ("Category 1", ...). Default FALSE.

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

PKanalix projects

Summary table of excluded records

R
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

R
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

R
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)

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

Last updated: