docs: correct adj.r.squared.factor, span.ratio, and aucint.inf description strings

R/PKNCA.options.R

@@ -4,9 +4,12 @@
   adj.r.squared.factor=function(x, default=FALSE, description=FALSE) {
     if (description)
       return(paste(
-        "The adjusted r^2 for the calculation of lambda.z has this factor",
-        "times the number of data points added to it.  It allows for more",
-        "data points to be preferred in the calculation of half-life."))
+        "During the calculation of lambda.z, all candidate regressions",
+        "with an adjusted r^2 within adj.r.squared.factor of the best",
+        "adjusted r^2 are considered acceptable, and the acceptable",
+        "regression using the most data points is selected.  It allows",
+        "for more data points to be preferred in the calculation of",
+        "half-life."))
     if (default)
       return(0.0001)
     if (length(x) != 1)

R/aucint.R

@@ -292,7 +292,7 @@ add.interval.col("aucint.inf.obs",
                  values=c(FALSE, TRUE),
                  unit_type="auc",
                  pretty_name="AUCint (based on AUCinf,obs extrapolation)",
-                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity with zeros (matching AUClast)",
+                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity using the half-life and the observed Clast (matching AUCinf,obs)",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose=NULL),
                  depends=c("lambda.z", "clast.obs"),
                  pptestcd_cdisc="AUCINTIS",
@@ -303,7 +303,7 @@ add.interval.col("aucint.inf.obs.dose",
                  values=c(FALSE, TRUE),
                  unit_type="auc",
                  pretty_name="AUCint (based on AUCinf,obs extrapolation, dose-aware)",
-                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity with zeros (matching AUClast) with dose-aware interpolation/extrapolation of concentrations",
+                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity using the half-life and the observed Clast (matching AUCinf,obs) with dose-aware interpolation/extrapolation of concentrations",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose="time.dose.group"),
                  depends=c("lambda.z", "clast.obs"),
                  pptestcd_cdisc="AUCINTID",
@@ -314,7 +314,7 @@ add.interval.col("aucint.inf.pred",
                  values=c(FALSE, TRUE),
                  unit_type="auc",
                  pretty_name="AUCint (based on AUCinf,pred extrapolation)",
-                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity with the triangle from Tlast to the next point and zero thereafter (matching AUCall)",
+                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity using the half-life and the predicted Clast (matching AUCinf,pred)",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose=NULL),
                  depends=c("lambda.z", "clast.pred"),
                  pptestcd_cdisc="AUCINTIP",
@@ -325,7 +325,7 @@ add.interval.col("aucint.inf.pred.dose",
                  values=c(FALSE, TRUE),
                  unit_type="auc",
                  pretty_name="AUCint (based on AUCinf,pred extrapolation, dose-aware)",
-                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity with the triangle from Tlast to the next point and zero thereafter (matching AUCall) with dose-aware interpolation/extrapolation of concentrations",
+                 desc="The area under the concentration time curve in the interval extrapolating from Tlast to infinity using the half-life and the predicted Clast (matching AUCinf,pred) with dose-aware interpolation/extrapolation of concentrations",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose="time.dose.group"),
                  depends=c("lambda.z", "clast.pred"),
                  pptestcd_cdisc="AUCINTPD",
@@ -443,7 +443,7 @@ add.interval.col("aumcint.inf.obs",
                  values=c(FALSE, TRUE),
                  unit_type="aumc",
                  pretty_name="AUMCint (based on AUMCinf,obs extrapolation)",
-                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity with zeros (matching AUMClast)",
+                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity using the half-life and the observed Clast (matching AUMCinf,obs)",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose=NULL),
                  depends=c("lambda.z", "clast.obs"))
 
@@ -453,7 +453,7 @@ add.interval.col("aumcint.inf.obs.dose",
                  values=c(FALSE, TRUE),
                  unit_type="aumc",
                  pretty_name="AUMCint (based on AUMCinf,obs extrapolation, dose-aware)",
-                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity with zeros (matching AUMClast) with dose-aware interpolation/extrapolation of concentrations",
+                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity using the half-life and the observed Clast (matching AUMCinf,obs) with dose-aware interpolation/extrapolation of concentrations",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose="time.dose.group"),
                  depends=c("lambda.z", "clast.obs"))
 
@@ -463,7 +463,7 @@ add.interval.col("aumcint.inf.pred",
                  values=c(FALSE, TRUE),
                  unit_type="aumc",
                  pretty_name="AUMCint (based on AUMCinf,pred extrapolation)",
-                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity with the triangle from Tlast to the next point and zero thereafter (matching AUMCall)",
+                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity using the half-life and the predicted Clast (matching AUMCinf,pred)",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose=NULL),
                  depends=c("lambda.z", "clast.pred"))
 
@@ -473,7 +473,7 @@ add.interval.col("aumcint.inf.pred.dose",
                  values=c(FALSE, TRUE),
                  unit_type="aumc",
                  pretty_name="AUMCint (based on AUMCinf,pred extrapolation, dose-aware)",
-                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity with the triangle from Tlast to the next point and zero thereafter (matching AUMCall) with dose-aware interpolation/extrapolation of concentrations",
+                 desc="The area under the moment curve in the interval extrapolating from Tlast to infinity using the half-life and the predicted Clast (matching AUMCinf,pred) with dose-aware interpolation/extrapolation of concentrations",
                  formalsmap=list(conc="conc.group", time="time.group", time.dose="time.dose.group"),
                  depends=c("lambda.z", "clast.pred"))
 

R/half.life.R

@@ -762,7 +762,7 @@ add.interval.col("span.ratio",
                  values=c(FALSE, TRUE),
                  unit_type="fraction",
                  pretty_name="Span ratio",
-                 desc="The ratio of the half-life to the duration used for half-life calculation",
+                 desc="The ratio of the lambda z regression time span to the half-life",
                  depends="half.life",
                  pptestcd_cdisc="LAMZSPN",
                  pptest_cdisc="Lambda z Span")

tests/testthat/test-PKNCA.options.R

@@ -467,6 +467,12 @@ test_that("PKNCA.options.describe", {
                info="Option descriptions are provided accurately.")
 })
 
+test_that("adj.r.squared.factor description matches the within-tolerance selection in the code (#582)", {
+  desc <- PKNCA:::PKNCA.options.describe("adj.r.squared.factor")
+  expect_match(desc, "within adj.r.squared.factor of the best adjusted r^2", fixed=TRUE)
+  expect_match(desc, "regression using the most data points is selected", fixed=TRUE)
+})
+
 test_that("PKNCA.options fails when setting defaults and another option simultaneously", {
   expect_error(
     PKNCA.options(default=TRUE, tau.choices=24),

tests/testthat/test-aucint.R

@@ -738,3 +738,51 @@ test_that("Integration functions are passed correctly through wrapper", {
   expect_true(is.numeric(auc_result) && auc_result > 0)
   expect_true(is.numeric(aumc_result) && aumc_result > 0)
 })
+
+test_that("aucint.inf descriptions state AUCinf extrapolation, not the AUClast/AUCall rules (#582)", {
+  cols <- get.interval.cols()
+  expect_match(
+    cols[["aucint.inf.obs"]]$desc,
+    "using the half-life and the observed Clast (matching AUCinf,obs)",
+    fixed=TRUE
+  )
+  expect_match(
+    cols[["aucint.inf.obs.dose"]]$desc,
+    "using the half-life and the observed Clast (matching AUCinf,obs) with dose-aware interpolation/extrapolation of concentrations",
+    fixed=TRUE
+  )
+  expect_match(
+    cols[["aucint.inf.pred"]]$desc,
+    "using the half-life and the predicted Clast (matching AUCinf,pred)",
+    fixed=TRUE
+  )
+  expect_match(
+    cols[["aucint.inf.pred.dose"]]$desc,
+    "using the half-life and the predicted Clast (matching AUCinf,pred) with dose-aware interpolation/extrapolation of concentrations",
+    fixed=TRUE
+  )
+})
+
+test_that("aumcint.inf descriptions state AUMCinf extrapolation, not the AUMClast/AUMCall rules (#582)", {
+  cols <- get.interval.cols()
+  expect_match(
+    cols[["aumcint.inf.obs"]]$desc,
+    "using the half-life and the observed Clast (matching AUMCinf,obs)",
+    fixed=TRUE
+  )
+  expect_match(
+    cols[["aumcint.inf.obs.dose"]]$desc,
+    "using the half-life and the observed Clast (matching AUMCinf,obs) with dose-aware interpolation/extrapolation of concentrations",
+    fixed=TRUE
+  )
+  expect_match(
+    cols[["aumcint.inf.pred"]]$desc,
+    "using the half-life and the predicted Clast (matching AUMCinf,pred)",
+    fixed=TRUE
+  )
+  expect_match(
+    cols[["aumcint.inf.pred.dose"]]$desc,
+    "using the half-life and the predicted Clast (matching AUMCinf,pred) with dose-aware interpolation/extrapolation of concentrations",
+    fixed=TRUE
+  )
+})

tests/testthat/test-half.life.R

@@ -996,3 +996,11 @@ test_that("pk.calc.half.life tobit manually.selected.points sets exclude for neg
     "Negative half-life estimated with manually-selected points"
   )
 })
+
+test_that("span.ratio description is the time span divided by the half-life, not the inverse (#582)", {
+  expect_match(
+    get.interval.cols()[["span.ratio"]]$desc,
+    "lambda z regression time span to the half-life",
+    fixed=TRUE
+  )
+})