docs: clarify three-state include/exclude_half.life semantics

NEWS.md

@@ -37,6 +37,13 @@ the dosing including dose amount and route.
 
 ## Improvements
 
+* Documentation for `include_half.life` and `exclude_half.life` now describes
+  the three-state (`TRUE`/`FALSE`/`NA`) per-point behavior, clarifies that a
+  column counts as "in use" whenever it is not entirely `NA` (so an all-`FALSE`
+  column still engages the method), and states that only one of the two may be
+  in use for the same interval. The half-life vignette gains the same note and
+  fixes a mislabeled "include" example.
+
 * The sparse NCA vignette now explains how subjects are grouped: sparse
   parameters pool all subjects that share the same concentration grouping
   variables with the subject column removed (#530).

R/class-PKNCAconc.R

@@ -28,11 +28,16 @@
 #' @param duration (optional) The duration of collection as is typically used
 #'   for concentration measurements in urine or feces.
 #' @param exclude_half.life,include_half.life A character scalar for the column
-#'   name in the dataset of the points to exclude from the half-life calculation
-#'   (still using normal curve-stripping selection rules for the other points)
-#'   or to include for the half-life (using specifically those points and
-#'   bypassing automatic curve-stripping point selection).  See the "Half-Life
-#'   Calculation" vignette for more details on the use of these arguments.
+#'   name in the dataset.  `exclude_half.life` names points to drop; automatic
+#'   curve-stripping point selection is still performed on the remaining
+#'   (non-excluded) points and is not bypassed.  `include_half.life` names the
+#'   exact points to use, bypassing automatic curve-stripping point selection.
+#'   Each value is `TRUE`, `FALSE`, or `NA` (undefined); a column is treated as
+#'   "in use" for an interval unless it is entirely `NA`, so leave it `NA`
+#'   (rather than `FALSE`) where the mechanism should not apply.  Only one of
+#'   `exclude_half.life` and `include_half.life` may be in use for a given
+#'   interval.  See the "Half-Life Calculation" vignette for more details on the
+#'   use of these arguments.
 #' @param lloq (optional) The lower limit of quantification used by the Tobit
 #'   half-life method (`hl_method = "tobit"`).  Either the name of a column in
 #'   `data` giving the per-observation LLOQ or a numeric scalar applied to all

R/pk.calc.all.R

@@ -351,11 +351,20 @@ pk.nca.intervals <- function(data_conc, data_dose, data_intervals, sparse,
 #' @param impute_method The method to use for imputation as a character string
 #' @param interval One row of an interval definition (see
 #'   [check.interval.specification()] for how to define the interval.
-#' @param include_half.life An optional boolean vector of the concentration
-#'   measurements to include in the half-life calculation. If given, no
-#'   half-life point selection will occur.
-#' @param exclude_half.life An optional boolean vector of the concentration
-#'   measurements to exclude from the half-life calculation.
+#' @param include_half.life An optional logical vector (one value per
+#'   concentration measurement) naming the points to use for the half-life. If
+#'   in use, automatic curve-stripping point selection is bypassed and exactly
+#'   the `TRUE` points are used for the half-life regression. `TRUE` uses the
+#'   point, `FALSE` does not, and `NA` is undefined; the vector is "in use" for
+#'   the interval unless it is entirely `NA` (so an all-`FALSE` vector still
+#'   counts as in use). At most one of `include_half.life` and
+#'   `exclude_half.life` may be in use for the same interval.
+#' @param exclude_half.life An optional logical vector (one value per
+#'   concentration measurement) naming points to drop before point selection.
+#'   Automatic curve-stripping point selection is still performed (it is not
+#'   bypassed) on the remaining, non-excluded points. `TRUE` excludes the point,
+#'   `FALSE` does not, and `NA` is undefined; the "in use" rule is the same as
+#'   for `include_half.life`.
 #' @param lloq An optional scalar or vector (the same length as `conc`) with the
 #'   lower limit of quantification passed to [pk.calc.half.life()] for the Tobit
 #'   half-life method.

vignettes/v06-half-life-calculation.Rmd

@@ -88,6 +88,13 @@ exclusion is applied (the interval is treated as-is, like the argument had not
 been given). If some values are `NA` for the interval, those are treated as
 `FALSE`.
 
+A column counts as in use for an interval whenever it contains any non-`NA`
+value, even if every value is `FALSE`. Only one of `exclude_half.life` and
+`include_half.life` may be in use for the same interval; supplying both raises
+the error "Cannot both include and exclude half-life points for the same
+interval". For this reason, initialize these columns to `NA` (rather than
+`FALSE`) when the corresponding method is not being used.
+
 ## Exclusion of Specific Points with Curve Stripping
 
 In some cases, specific points will be known outliers, or there may be another reason to exclude specific points.  And, with those points excluded, the half-life should be calculated using the normal curve stripping methods described above.
@@ -121,14 +128,14 @@ as.data.frame(result_obj_exclude1)
 
 In other cases, the exact points to use for half-life calculation are known, and automatic point selection with curve stripping should not be performed.
 
-To exclude specific points but otherwise use curve stripping, use the `include_half.life` option as the column name in the concentration dataset for `PKNCAconc()` as illustrated below.
+To use only specific points and bypass automatic curve stripping, use the `include_half.life` option as the column name in the concentration dataset for `PKNCAconc()` as illustrated below.
 
 ```{r include-points}
 data_conc$include_hl <- data_conc$Time > 3
-# Confirm that we will be excluding exactly one point
+# Confirm that we will be including exactly six points
 stopifnot(sum(data_conc$include_hl) == 6)
 
-# Drop one point
+# Use only these points for the half-life
 conc_obj_include6 <-
   PKNCAconc(
     data_conc,