V0.11.0

The validation summary now carries the predictor into the result so relative CI widths are computed against the predictor's 10th–90th percentile spread instead of a self-referential bootstrap proxy. Stability tiers are assigned consistently and exposed via a machine-readable `stability` list, and package metadata plus the bilirubin/CRC vignettes were updated to reflect the revised reporting and wording.

Author: paytonyau

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: OptSurvCutR
 Type: Package
 Title: Optimal Survival Cut-Point Discovery for Time-to-Event Analysis with 'OptSurvCutR'
-Version: 0.10.1
+Version: 0.11.0
 Authors@R: 
     c(person(given = "Payton",
              family = "Yau",
@@ -11,7 +11,8 @@ Authors@R:
       person(given = "Suhirthakumar",
              family = "Puvanendran",
              role = "aut",
-             email = "kumar.puvan@uwl.ac.uk"))
+             email = "kumar.puvan@uwl.ac.uk",
+             comment = c(ORCID = "0000-0003-2346-0483")))
 Description: Provides a robust workflow for optimal cut-point analysis in
     time-to-event ('survival') data. Functions determine the optimal number
     of cut-points via find_cutpoint_number(), find their precise locations

NEWS.md

@@ -1,3 +1,106 @@
+# OptSurvCutR v0.11.0 (2026-09-08)
+
+The validation summary now carries the predictor into the result, so relative confidence
+interval widths are computed against the predictor's 10th–90th percentile spread rather
+than a self-referential bootstrap proxy. Stability tiers are assigned consistently and
+exposed through a machine-readable `stability` list. Both case study vignettes and the
+package documentation have been updated to reflect the revised reporting.
+
+## Bug Fixes (Important)
+
+* **Stability Metric Denominator:** `summary.validate_cutpoint_result()` computed the
+  relative confidence interval width against the bootstrap distribution of the first
+  cut-point rather than the 10th–90th percentile range of the predictor. The cause was
+  that `validate_cutpoint()` did not carry the `userdata` element into its returned
+  object, so the predictor values were unavailable to the summary method and an internal
+  fallback was silently used instead. Reported relative widths were consequently inflated
+  by roughly an order of magnitude, and **Stability Tier 1 was unreachable for any
+  input**. Stability tiers reported by version 0.10.1 and earlier should be recomputed.
+
+* **Removal of Silent Fallbacks:** The two fallback denominators
+  (`bootstrap_distribution[, 1]` and `max(abs(medians))`) have been removed. Where the
+  predictor values are unavailable, or where the 10th and 90th percentiles of a highly
+  discrete predictor coincide, the relative width is now reported as undefined with a
+  diagnostic message rather than substituted with an unrelated quantity.
+
+* **Single Cut-point Classification:** Models with one cut-point have no adjacent
+  interval, so interval separation is undefined and `has_distinct_separation` could never
+  evaluate to `TRUE`. Such models could therefore only be assigned Tier 1 or Tier 4.
+  Single-threshold models are now graded on relative width alone (< 30% Tier 1, 30–60%
+  Tier 2, > 60% Tier 4) and can no longer be assigned Tier 3, which requires overlap.
+
+## API Changes
+
+* **Machine-readable Stability Output:** `summary.validate_cutpoint_result()` now attaches
+  a `stability` list to the returned object, containing `tier`, `tier_label`, `percent`,
+  `max_relative_width`, `relative_widths` (per cut-point), `data_spread`, `separated` and
+  `worst_cut`. Tier assignment and interval widths can now be accessed programmatically
+  instead of parsed from console output, which supports batch screening of multiple
+  predictors.
+
+* **Predictor Values Retained:** `validate_cutpoint()` now returns the analysis data in
+  the `userdata` element, consistent with `find_cutpoint()`.
+
+## Documentation
+
+* **Tier Classification Documentation:** Clarified that the four tiers summarise two
+  independent diagnostics — interval separation and relative width — and do not constitute
+  an ordinal scale; whether Tier 2 or Tier 3 is preferable depends on whether separation
+  or boundary precision matters for the intended application. Documented that the 30% and
+  60% boundaries are pragmatic conventions adopted for interpretability rather than
+  calibrated thresholds.
+
+* **Diagnostic Messaging:** Where stability cannot be calculated, the message now
+  identifies the required input (`userdata$factor`) and the conditions under which the
+  metric is undefined.
+
+* **Console Messages:** Corrected spelling in three user-facing messages in the systematic
+  search engine, and generalised a hard-coded message to report the number of candidate
+  positions and cut-points actually being searched.
+
+* **Standards Compliance:** Expanded `@srrstats {G1.1}` to document the methodological
+  origin of the approach (maximally selected rank statistics, information-theoretic model
+  selection, multivariable Cox optimisation, and bootstrap resampling), and to clarify
+  that the multi-threshold problem lies outside the stated scope of `maxstat`, `survminer`
+  and `cutpointr` rather than representing a deficiency in those packages. Narrowed
+  `@srrstats {G1.5}` to describe the comparison actually provided.
+
+* **Vignettes:** Both case study vignettes were re-run against the corrected metric and
+  the reported stability tiers updated accordingly. Guidance on replicate counts,
+  permutation counts and the interpretation of overlapping confidence intervals has been
+  expanded, and clinical background added for both cohorts.
+
+* **README:** Replaced the simulated example, in which the information criterion selected
+  zero cut-points, with the Mayo Clinic PBC analysis reported in the manuscript. Revised
+  language describing what the bootstrap assessment establishes, and reserved claims of
+  rOpenSci compliance until review has concluded.
+
+## Testing
+
+* **Regression Coverage:** Added `tests/testthat/test-stability-metric.R`, verifying that
+  `userdata` survives into the validation object, that the relative width is computed
+  against the predictor's percentile range and not the bootstrap distribution, that
+  single-cut models are never assigned Tier 3, that undefined cases return no tier rather
+  than an incorrect one, and that `summary()` returns the documented `stability` fields.
+
+* **Reachability Test:** Added an explicit test that Tier 1 is attainable for a
+  well-separated threshold in a large sample. The defect above was characterised by an
+  entire classification category being unreachable, which value-comparison tests alone
+  would not have detected.
+
+* **Workflow Integration Tests:** Added `tests/testthat/test-workflow-integration.R`,
+  which runs the three core functions in sequence and asserts that state is preserved
+  across them: the number of thresholds located matches the number selected, one
+  confidence interval and one relative width is reported per threshold, the predictor is
+  identical at every stage, and covariates used during the search are reused during
+  validation. Both defects fixed in this release were handoff failures between functions
+  rather than faults within them, which unit tests cannot detect.
+
+## Dependencies
+
+* No changes to package dependencies in this release.
+
+
 # OptSurvCutR v0.10.1 (2026-04-09)
 
 ## Documentation & Standards Compliance

R/engine-systematic.R

@@ -6,7 +6,7 @@
 #' Internal helper: Systematic Grid Search over Regulared Space
 #'
 #' @description
-#' Implements an exhaustive grid search over a regulared percentile space
+#' Implements an exhaustive grid search over a regularised percentile space
 #' to evaluate possible thresholds for 1 or 2 cut-points, respecting the minimum
 #' group size constraints.
 #'
@@ -30,7 +30,7 @@
 .systematic_search <- function(userdata, num_cuts, criterion,
                                covariates, nmin, predictor_name,
                                quiet, candidate_cuts = NULL, ...) {
-  if (!quiet) cli::cli_alert_info("Running regulared systematic search for {num_cuts} cut-point(s)...")
+  if (!quiet) cli::cli_alert_info("Running regularised systematic search for {num_cuts} cut-point(s)...")
   userdata <- userdata[order(userdata$factor), ]
 
   cov_part <- if (!is.null(covariates)) paste(" +", paste(covariates, collapse = " + ")) else ""
@@ -66,7 +66,7 @@
   best_cut_val <- rep(NA_real_, num_cuts)
   all_stats_df <- NULL
 
-  # Establish the core regulared grid structure
+  # Establish the core regularised grid structure
   if (!is.null(candidate_cuts)) {
     search_grid <- candidate_cuts
   } else {
@@ -95,7 +95,7 @@
     best_stat <- stats_per_cut[best_idx]
     all_stats_df <- data.frame(cut1 = search_grid, stat = stats_per_cut)
   } else { # num_cuts == 2
-    if (!quiet) cli::cli_alert_info("Searching for 2 cuts over regulared coordinate space...")
+    if (!quiet) cli::cli_alert_info("Searching over {length(search_grid)} candidate positions for {num_cuts} cut(s)...")
     foreach::registerDoSEQ()
 
     if (length(search_grid) < 2) {
@@ -137,7 +137,7 @@
     all_stats_df <- results_list
   }
 
-  if (!quiet) cli::cli_alert_success("Systematic grid optimation complete.")
+  if (!quiet) cli::cli_alert_success("Systematic grid optimisation complete.")
   return(list(
     optimal_cuts = best_cut_val,
     optimal_stat = best_stat,
@@ -225,7 +225,7 @@
 #' Internal helper: Systematic Model Selection and Delta IC Range Mining
 #'
 #' @description
-#' Evaluates models from 1 to `max_cuts` using the regulared systematic
+#' Evaluates models from 1 to `max_cuts` using the regularised systematic
 #' sweeper, computing Information Criteria (AIC/BIC) and profiling the permissible range.
 #'
 #' @param userdata Cleaned survival data frame.

R/find_cutpoint.R

@@ -13,19 +13,52 @@
 #'
 #' @section srrstats compliance:
 #' .
-#' @srrstats {G1.1} Grounded in information-theoretic model selection (AIC/BIC)
-#'   and multivariable survival optimization (Cox/log-rank) via exhaustive grid
-#'   search (k <= 2) and genetic algorithms via `rgenoud` (k > 2). Whereas tools
-#'   like `survminer` and `cutpointr` focus strictly on univariate single splits
-#'   (k = 1), OptSurvCutR optimizes multiple thresholds simultaneously under active
-#'   covariate adjustment with bootstrap stability validation. Accelerated using
-#'   base `Rcpp` (`src/matrix_factory.cpp`) for discrete index binning without external
-#'   linear algebra libraries.
+#' @srrstats {G1.1} This package implements an established approach — outcome-oriented
+#'   cut-point selection for censored survival data — and extends it in four key
+#'   directions. The methodological origin is the maximally selected rank statistic
+#'   (Miller & Siegmund 1982; Lausen & Schumacher 1992), in which a log-rank statistic
+#'   is maximised over candidate thresholds and the resulting p-value corrected for the
+#'   selection. Faraggi & Simon (1996) established by simulation that uncorrected
+#'   selection inflates Type I error and biases effect estimates, and Rota et al. (2015)
+#'   compared correction strategies for censored outcomes. These references define the
+#'   single-threshold problem that `maxstat`, `survminer::surv_cutpoint()`, and
+#'   `cutpointr` address.
+#'
+#'   Those packages are not deficient implementations of a multi-threshold method; the
+#'   multi-threshold problem is outside their stated scope. `cutpointr` is designed for
+#'   binary classification metrics and optimises a single cut-point over measures such as
+#'   the Youden index; `maxstat` computes asymptotic approximations and exact null
+#'   distributions of maximally selected rank statistics for a single split; `survminer`
+#'   provides a plotting-oriented interface to the latter. Where a single unadjusted
+#'   threshold answers the question, these remain appropriate tools.
+#'
+#'   `OptSurvCutR` addresses four methodological problems that fall outside that scope:
+#'   1. Number of thresholds: Treated as a model selection problem rather than fixed a
+#'      priori, using information criteria (Akaike 1974; Schwarz 1978) across candidate
+#'      complexities.
+#'   2. Simultaneous optimisation: Multiple thresholds are optimised simultaneously rather
+#'      than sequentially, using exhaustive enumeration for k <= 2 and an evolutionary
+#'      genetic algorithm (Mebane & Sekhon 2011, via `rgenoud`) for k > 2, avoiding the
+#'      path-dependence of hierarchical splitting.
+#'   3. Confounder control: Thresholds are selected within a multivariable Cox model
+#'      (Cox 1972), evaluating candidate boundaries conditionally on clinical covariates
+#'      rather than marginally.
+#'   4. Threshold reproducibility: Non-parametric bootstrap resampling (Efron 1979)
+#'      re-runs the search across resampled cohorts to quantify spatial stability. While
+#'      a permutation-corrected p-value establishes that an observed separation is unlikely
+#'      under the null, the bootstrap CI reports whether the threshold coordinate itself
+#'      is reproducible across comparable patient samples.
+#'
+#'   Numerical implementation uses base `Rcpp` (`src/matrix_factory.cpp`) for discrete
+#'   index binning, without external linear algebra dependencies.
 #' @srrstats {G1.0} References provided for Cox, log-rank, genetic optimisation.
 #' @srrstats {G1.3} Systematic grid search (1–2 cuts) and `rgenoud` global
 #'   optimisation documented.
-#' @srrstats {G1.5} Compared with `cutpointr` and `survminer` in package
-#'   vignette.
+#' @srrstats {G1.5} A feature-level comparison against `maxstat`, `survminer`,
+#'   `CutpointsOEHR`, Evaluate Cutpoints, X-tile and Cutoff Finder is provided in the
+#'   accompanying manuscript, and against `maxstat`/`survminer` in the bilirubin
+#'   vignette. Numerical comparison of results across implementations is not attempted,
+#'   as the packages address different estimands.
 #' @srrstats {G1.6} Numerical stability via `survival::coxph` and `rgenoud`;
 #'   edge cases return `NA`.
 #' @srrstats {G2.3a} Uses `match.arg()` to validate `method` and `criterion`
@@ -63,30 +96,49 @@
 #' @srrstats {RE2.4a} Checks for collinearity among predictors.
 #' @srrstats {RE2.4b} Checks for collinearity between X and Y.
 #'
-#' @details
-#' `method = "systematic"`: grid search respecting `nmin`. Optimised via internal quantiles.
-#' `method = "genetic"`: `rgenoud` global optimisation.
-#' Systematic search is slow for `num_cuts > 2`; use `genetic`.
-#' Core vector partitions are calculated in compiled C++ via `Rcpp` for optimal performance.
-#'
 #' @references
-#' Altman, D. G., Lausen, B., Sauerbrei, W., & Schumacher,
-#' M. (1994). Dangers of Using “Optimal” Cutpoints in the Evaluation of
-#' Prognostic Factors. *JNCI: Journal of the National Cancer Institute*,
-#' 86(11), 829–835. \doi{10.1093/jnci/86.11.829}
+#' Akaike, H. (1974). A new look at the statistical model identification.
+#' *IEEE Transactions on Automatic Control*, 19(6), 716–723.
+#' \doi{10.1109/TAC.1974.1100705}
+#'
+#' Altman, D. G., Lausen, B., Sauerbrei, W., & Schumacher, M. (1994). Dangers
+#' of using "optimal" cutpoints in the evaluation of prognostic factors.
+#' *JNCI: Journal of the National Cancer Institute*, 86(11), 829–835.
+#' \doi{10.1093/jnci/86.11.829}
+#'
+#' Cox, D. R. (1972). Regression models and life-tables. *Journal of the
+#' Royal Statistical Society: Series B (Methodological)*, 34(2), 187–202.
+#' \doi{10.1111/j.2517-6161.1972.tb00899.x}
+#'
+#' Efron, B. (1979). Bootstrap methods: Another look at the jackknife.
+#' *The Annals of Statistics*, 7(1), 1–26. \doi{10.1214/aos/1176344552}
+#'
+#' Faraggi, D., & Simon, R. (1996). A simulation study of cross-validation for
+#' selecting an optimal cutpoint in univariate survival analysis.
+#' *Statistics in Medicine*, 15(20), 2203–2213.
+#' \doi{10.1002/(SICI)1097-0258(19961030)15:20<2203::AID-SIM357>3.0.CO;2-G}
+#'
+#' Lausen, B., & Schumacher, M. (1992). Maximally selected rank statistics.
+#' *Biometrics*, 48(1), 73–85. \doi{10.2307/2532740}
+#'
+#' Mantel, N. (1966). Evaluation of survival data and two new rank order
+#' statistics arising in its consideration. *Cancer Chemotherapy Reports*,
+#' 50(3), 163–170.
+#'
+#' Mebane Jr, W. R., & Sekhon, J. S. (2011). Genetic optimization using
+#' derivatives: The rgenoud package for R. *Journal of Statistical Software*,
+#' 42(11), 1–26. \doi{10.18637/jss.v042.i11}
 #'
-#' Cox, D. R. (1972). Regression Models and Life-Tables. *Journal
-#' of the Royal Statistical Society: Series B (Methodological)*, 34(2),
-#' 187–202. \doi{10.1111/j.2517-6161.1972.tb00899.x}
+#' Miller, R., & Siegmund, D. (1982). Maximally selected chi square statistics.
+#' *Biometrics*, 38(4), 1011–1016. \doi{10.2307/2529881}
 #'
-#' Mantel, N. (1966). Evaluation of survival data and two new
-#' rank order statistics arising in its consideration. *Cancer
-#' Chemotherapy Reports*, 50(3).
+#' Rota, M., Antolini, L., & Valsecchi, M. G. (2015). Optimal cut-point
+#' definition in biomarkers: The case of censored failure time outcome.
+#' *BMC Medical Research Methodology*, 15(1), 24.
+#' \doi{10.1186/s12874-015-0009-y}
 #'
-#' Mebane Jr, W. R., & Sekhon, J. S. (2011). Genetic
-#' Optimisation Using Derivatives: The rgenoud Package for R.
-#' *Journal of Statistical Software*, 42, 1–26.
-#' \doi{10.18637/jss.v042.i11}
+#' Schwarz, G. (1978). Estimating the dimension of a model. *The Annals of
+#' Statistics*, 6(2), 461–464. \doi{10.1214/aos/1176344136}
 #'
 #' @param data A data frame containing the analysis variables.
 #' @param predictor The continuous predictor variable name (character).

R/validate_cutpoint.R

@@ -351,6 +351,10 @@ validate_cutpoint <- function(cutpoint_result, num_replicates = 500,
     confidence_intervals = ci_df,
     bootstrap_distribution = bootstrap_df,
     boot_summary = boot_summary,
+    # Carry the analysis data forward so that summary() can compute the
+    # relative CI width against the spread of the PREDICTOR. Without this,
+    # summary() falls back to an incorrect denominator.
+    userdata = cutpoint_result$userdata,
     parameters = list(
       num_replicates = num_replicates,
       successful_reps = successful_reps,