feat: add option to drop end-interval concentration for regular parameters

Author: Gero1999

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: aNCA
 Title: (Pre-)Clinical NCA in a Dynamic Shiny App
-Version: 0.1.0.9185
+Version: 0.1.0.9186
 Authors@R: c(
     person("Ercan", "Suekuer", email = "ercan.suekuer@roche.com", role = "aut",
            comment = c(ORCID = "0009-0001-1626-1526")),

NAMESPACE

@@ -10,6 +10,7 @@ export(PKNCA_build_units_table)
 export(PKNCA_calculate_nca)
 export(PKNCA_create_data_object)
 export(PKNCA_hl_rules_exclusion)
+export(PKNCA_impute_method_end_conc_drop)
 export(PKNCA_impute_method_start_c1)
 export(PKNCA_impute_method_start_logslope)
 export(PKNCA_update_data_object)

NEWS.md

@@ -25,6 +25,7 @@
 * Partial interval parameters section supports calculations beyond `AUCINT`: `RCAMINT`, `AUCINTD`, `CAVGINT`, and others. Table starts empty by default with a Remove Row button (#524, #1249)
 * "Min. Points for Half-life" setting added (range 2–10, default 3) (#1155)
 * BLQ imputation rules via `NCA Setup > Data Imputation` (#139)
+* "Drop End Concentration" switch in `NCA Setup > Data Imputation` drops the concentration at the end of each main interval before regular parameter calculations (partial/interval parameters unaffected) (#TODO)
 * General Exclusions section for in-app NCA exclusions, with "Excl. TLG" checkbox per entry (#851, #1018)
 * Parameter Exclusions tab: exclude individual PK parameter rows from descriptive statistics and ADPP export via PPSUMFL/PPSUMRSN flags (#1040)
 * NCA flag rules (NCAwXRS) from ADNCA standards — flagged records are excluded from NCA (#752)

R/PKNCA.R

@@ -283,6 +283,9 @@ PKNCA_create_data_object <- function( # nolint: object_name_linter
 #' (forwarded to [update_main_intervals()]).
 #' @param blq_imputation_rule Optional list defining the BLQ imputation rule
 #' (forwarded to [update_main_intervals()]).
+#' @param drop_end_conc Logical indicating whether to drop the concentration at
+#' the end of each main interval for regular parameters (forwarded to
+#' [update_main_intervals()]). Default `FALSE`.
 #' @param custom_units_table Optional data frame with PPSTRESU overrides.
 #' When provided, applied via [dplyr::rows_update()] on the PKNCAdata units table.
 #'
@@ -308,6 +311,7 @@ PKNCA_update_data_object <- function( # nolint: object_name_linter
   parameter_selections = NULL,
   int_parameters = NULL,
   blq_imputation_rule = NULL,
+  drop_end_conc = FALSE,
   custom_units_table = NULL) {
 
   data <- adnca_data
@@ -371,7 +375,8 @@ PKNCA_update_data_object <- function( # nolint: object_name_linter
     parameter_selections = parameter_selections,
     int_parameters = int_parameters,
     impute = start_impute,
-    blq_imputation_rule = blq_imputation_rule
+    blq_imputation_rule = blq_imputation_rule,
+    drop_end_conc = drop_end_conc
   )
 
   # Apply custom units table
@@ -583,6 +588,45 @@ PKNCA_impute_method_start_c1 <- function(conc, time, start, end, ..., options =
   d_conc_time
 }
 
+#' Drop the concentration measured exactly at the end of the interval
+#'
+#' Removes a concentration sitting exactly at `time == end` for an interval, if
+#' one is present (no-op otherwise). This is typically used with multiple-dose
+#' data where the boundary point belongs to the next dose (e.g. an imputed C0),
+#' so it should not contribute to parameters on the current interval.
+#'
+#' @param conc Numeric vector of concentrations.
+#' @param time Numeric vector of times corresponding to the concentrations.
+#' @param end Numeric value (or vector) indicating the end time of the interval.
+#' @param ... Additional arguments (currently not used).
+#' @param options List of options (currently not used).
+#'
+#' @returns A data frame of `conc`/`time` with any end-boundary point removed.
+#' @details
+#' This function adheres to the structure required by the `PKNCA` package to work
+#' with its imputation functionality. For more information, see the
+#' [PKNCA Data Imputation Vignette](https://CRAN.R-project.org/package=PKNCA).
+#'
+#' TODO(end_conc_drop): remove this local copy once humanpred/pknca#572 is merged
+#' and aNCA depends on a PKNCA release that exports
+#' `PKNCA_impute_method_end_conc_drop()`. At that point drop this definition and
+#' the corresponding `@export`/NAMESPACE entry and rely on the PKNCA-native method.
+#' @export
+#'
+#' @examples
+#' conc <- c(10, 5, 1)
+#' time <- c(0, 12, 24)
+#' end <- 24
+#' PKNCA_impute_method_end_conc_drop(conc, time, end)
+PKNCA_impute_method_end_conc_drop <- function(conc, time, end, ..., options = list()) { # nolint
+  d_conc_time <- data.frame(conc = conc, time = time)
+  mask_end <- time %in% end
+  if (any(mask_end)) {
+    d_conc_time <- d_conc_time[!mask_end, , drop = FALSE]
+  }
+  d_conc_time
+}
+
 #' Build Units Table for PKNCA
 #'
 #' This function generates a PKNCA units table including the potential unit segregating columns

R/intervals.R

@@ -206,6 +206,10 @@ format_pkncadata_intervals <- function(pknca_conc,
 #' Each element can be a numeric value (substituting the BLQ value), or a string such as
 #' `"drop"` (ignores the value) or `"keep"` (keeps the value as 0). Default is NULL,
 #' which does not specify any BLQ imputation in any interval.
+#' @param drop_end_conc Logical. If `TRUE`, the concentration measured exactly at
+#' the end of each main interval is dropped before regular (non-partial) parameter
+#' calculations via the `end_conc_drop` imputation. This does not affect
+#' interval/partial parameter rows (`type_interval == "manual"`). Default `FALSE`.
 #'
 #' @importFrom dplyr left_join mutate across where select all_of if_else bind_rows filter
 #' @importFrom dplyr group_by ungroup slice_max distinct
@@ -217,7 +221,8 @@ update_main_intervals <- function(
   parameter_selections = NULL,
   int_parameters = NULL,
   impute = TRUE,
-  blq_imputation_rule = NULL
+  blq_imputation_rule = NULL,
+  drop_end_conc = FALSE
 ) {
 
   if (is.null(parameter_selections)) parameter_selections <- list()
@@ -305,6 +310,24 @@ update_main_intervals <- function(
       )
   }
 
+  ############################################
+  # Drop the end-boundary concentration for regular parameters (main intervals
+  # only). Partial/interval parameters (type_interval == "manual") are untouched.
+  if (isTRUE(drop_end_conc)) {
+    data$intervals <- data$intervals %>%
+      mutate(
+        impute = ifelse(
+          type_interval == "main",
+          ifelse(
+            is.na(impute) | impute == "",
+            "end_conc_drop",
+            paste0(impute, ", end_conc_drop")
+          ),
+          impute
+        )
+      )
+  }
+
   ############################################
   # Remove any imputation from the observational parameters
   data <- rm_impute_obs_params(data, metadata_nca_parameters)

inst/shiny/modules/tab_nca/nca_setup.R

@@ -134,7 +134,8 @@ nca_setup_server <- function(id, data, adnca_data, extra_group_vars, settings_ov
         min_hl_points = settings()$min_hl_points,
         parameter_selections = parameters_output$selections(),
         int_parameters = settings()$int_parameters,
-        blq_imputation_rule = settings()$data_imputation$blq_imputation_rule
+        blq_imputation_rule = settings()$data_imputation$blq_imputation_rule,
+        drop_end_conc = settings()$data_imputation$drop_end_conc
       )
 
       # Wait for study types to settle during reactive transitions

inst/shiny/modules/tab_nca/setup/data_imputation.R

@@ -128,6 +128,44 @@ data_imputation_ui <- function(id) {
           width = "500px"
         )
       )
+    ),
+    hr(),
+    # Drop end-of-interval concentration widget and help button
+    fluidRow(
+      column(
+        width = 10,
+        input_switch(
+          id = ns("drop_end_conc"),
+          label = "Drop End Concentration",
+          value = FALSE
+        )
+      ),
+      column(
+        width = 2,
+        dropdown(
+          div(
+            tags$h2("Drop End Concentration Help"),
+            p(
+              "Drops the concentration measured exactly at the end of each",
+              "interval before regular (non-partial) parameter calculations.",
+              "Only applies to main intervals; partial/interval parameters are",
+              "left untouched."
+            ),
+            p(
+              "This is useful for multiple-dose data where the concentration at",
+              "the interval end really belongs to the next dose (e.g. an imputed",
+              "C0). Including it can distort parameters such as Cmax, Tmax and AUC;",
+              "genuine troughs are unaffected when the point does not sit exactly",
+              "at the interval end."
+            )
+          ),
+          style = "unite",
+          right = TRUE,
+          icon = icon("question"),
+          status = "primary",
+          width = "500px"
+        )
+      )
     )
   )
 }
@@ -149,6 +187,11 @@ data_imputation_server <- function(id, settings_override) {
         update_switch("should_impute_c0", value = imputation$impute_c0)
       }
 
+      # Restore drop_end_conc switch
+      if (!is.null(imputation$drop_end_conc)) {
+        update_switch("drop_end_conc", value = imputation$drop_end_conc)
+      }
+
       # Restore BLQ strategy dropdown
       valid_strategies <- c(
         "Tmax based imputation",
@@ -249,6 +292,7 @@ data_imputation_server <- function(id, settings_override) {
 
     list(
       should_impute_c0 = reactive(input$should_impute_c0),
+      drop_end_conc = reactive(input$drop_end_conc),
       blq_strategy = reactive(input$select_blq_strategy),
       blq_imputation_rule = blq_imputation_rule
     )

inst/shiny/modules/tab_nca/setup/settings.R

@@ -460,6 +460,7 @@ settings_server <- function(id, data, adnca_data, settings_override) {
         min_hl_points = input$min_hl_points,
         data_imputation = list(
           impute_c0 = data_imputation$should_impute_c0(),
+          drop_end_conc = data_imputation$drop_end_conc(),
           blq_strategy = data_imputation$blq_strategy(),
           blq_imputation_rule = data_imputation$blq_imputation_rule()
         ),

inst/www/templates/clinical_template.yaml

@@ -2,6 +2,7 @@ settings:
   method: lin up/log down
   data_imputation:
     impute_c0: yes
+    drop_end_conc: no
     blq_strategy: No BLQ handling
     blq_imputation_rule:
       first: keep

inst/www/templates/preclinical_LM_template.yaml

@@ -3,6 +3,7 @@ settings:
   bioavailability: f_aucinf.obs
   data_imputation:
     impute_c0: yes
+    drop_end_conc: no
     blq_strategy: Set value for all BLQ
     blq_imputation_rule:
       first: drop