NEWS

OptSurvCutR 0.11.2

New Features

Genetic Search Seed Warning: find_cutpoint() and find_cutpoint_number() now warn when method = "genetic" is used without an explicit seed. rgenoud's evolutionary search is stochastic; without a fixed seed, two calls on identical data and arguments can converge to different cut-point locations. The warning states this plainly and points to seed = <integer> as the fix. In find_cutpoint(), this warning is intentionally not gated behind quiet, unlike this function's other informational messages, so its behaviour matches find_cutpoint_number()'s equivalent warning, which has no quiet argument to gate behind in the first place.
max_cuts Ceiling Warning: find_cutpoint_number() now warns when the selected model's num_cuts equals the max_cuts ceiling supplied by the caller. A model landing exactly at the ceiling means the search was never permitted to consider a more complex architecture that might fit better — the warning flags this and suggests re-running with a higher max_cuts to check. This directly addresses a real case found during testing: a search capped at max_cuts = 2 selected the 2-cut model as best, while re-running with max_cuts = 5 on the same data found a 3-cut model with a lower (better) BIC that the capped search could never have found.

Documentation & Maintenance

Genetic Search Budget Table: The reference table of default pop.size/max.generations values by cut-point count now includes the genetic engine's defaults at $K=1$ and $K=2$ (30/30 and 60/40 respectively), which exist in the code but were previously shown only for systematic at those complexities. Added a note clarifying that a larger search budget improves the quality of a genetic search's result but does not by itself guarantee repeatability — only an explicit seed does that.

| Target Complexity ($K$ Cuts) | Execution Method | Default Population Size (pop.size) | Default Search Lifespan (max.generations) | Optimisation Mechanics | | --- | --- | --- | --- | --- | | $K = 1$ Cut | systematic (recommended) | N/A (Exhaustive Grid) | N/A (Exhaustive Grid) | Full 1D Coordinate Vector Sweep | | $K = 1$ Cut | genetic | 30 | 30 | 1D Index Search (rarely needed — systematic is exhaustive and faster here) | | $K = 2$ Cuts | systematic (recommended) | N/A (Exhaustive Grid) | N/A (Exhaustive Grid) | Full 2D Cross-Lattice Matrix Sweep | | $K = 2$ Cuts | genetic | 60 | 40 | 2D Index Search (not guaranteed to match systematic's exhaustive result — see note below) | | $K = 3$ Cuts | genetic (required) | 100 | 50 | 3D Index Hyper-Lattice Traversal | | $K = 4$ Cuts | genetic (required) | 120 | 55 | 4D Hyper-Lattice Spatial Search | | $K = 5$ Cuts | genetic (required) | 150 | 60 | 5D Multi-Epitope Surface Clustering | | $K = 6$ Cuts | genetic (required) | 180 | 65 | 6D High-Dimensional Coordinate Scan | | $K = 7$ Cuts | genetic (required) | 200 | 70 | 7D Ultra-Deep Hyper-Volume Optimization | | $K \ge 8$ Cuts | genetic (required) | 250 | 80 | Complex Deep Lattice Cluster Optimisation | | Low-Density Data (Discrete) | systematic | N/A (Auto-collapsed) | N/A (Auto-collapsed) | Rigid Quantile Step Filtering / Cell Floor Defence | | Validation / Bootstrap Loop | Context Snapped | 10 (Streamlined default) | 2 (Streamlined default) | Accelerated Resampling Stability Assessment |

systematic is exhaustive at $K \le 2$ — it evaluates every possible cut position (or every pair, for $K=2$) on the candidate grid, so it is guaranteed to find the best available answer and is required above $K=2$, where exhaustive search becomes computationally impractical. **pop.size/max.generations control search quality, not *repeatability.** A larger budget makes geneticmore likely to find the true optimum on repeat runs, but does not guarantee identical results between runs on its own. Always pass an explicitseedwhen usingmethod = "genetic"` for a reproducible result; as of this version, the package emits a warning if no seed is supplied.

OptSurvCutR 0.11.1 (2026-09-18)

Breaking Changes

Stability Tier Labels Renamed: Renamed tier_label values from "DISTINCT" to "CONSISTENT" and "CAUTION" to "OVERLAPPING" in validate_cutpoint() outputs to describe interval overlap directly. Numeric tier designations ("Tier 1"–"Tier 4"), cutoffs, and logic remain unchanged. Removed internal diagnostic tags ("- OVERLAP DOWNGRADE", "- SEPARATION OVERRIDE"). Downstream code matching literal strings "DISTINCT" or "CAUTION" must be updated.

New Features

Console Control (quiet = TRUE): Added a quiet parameter (default FALSE) to validate_cutpoint() to suppress progress bars in scripted pipelines and automated test suites.
Test Performance Optimization: Configured options(cli.progress_show_after = Inf) across package tests and vignettes to bypass CLI rendering overhead, reducing local test-suite runtime by ~65% (~418s vs. ~1215s) with zero skipped test logic.

Bug Fixes

Unadjusted p_value Search: Fixed null log-likelihood extraction in .get_stat() from coxph(~ 1) when covariates = NULL, resolving an issue where find_cutpoint_number(method = "systematic") failed screening and defaulted to 0 cuts.
Permutation Tail Direction: Corrected .run_permutations() for criterion = "p_value" to evaluate test statistics against the empirical lower tail (<=) rather than the upper tail.
Schoenfeld Residual Faceting: Updated plot_cutpoint_residuals() to extract column-separated residuals via residuals(fit, type = "schoenfeld"), rendering separate diagnostic panels for each non-reference risk tier.
Survival Plot Label: Updated default Kaplan-Meier y-axis label in .plot_km_curve() to endpoint-neutral "Survival Probability".

Code Consolidation & Architecture

S3 Method De-duplication: Removed stale, redundant definitions of print(), summary(), and plot() from find_cutpoint_number.R, centralizing canonical implementations in find_cutpoint_number_methods.R.
Helper Consolidation: Removed duplicate .calc_ic() from engine-genetic.R, standardizing on utils-helpers.R as the single source.

Documentation & Maintenance

Example Optimization: Replaced the find_cutpoint_number() example with a fast (<1s) synthetic two-cluster simulation to eliminate execution-time NOTEs.
Console Wording: Updated the validate_cutpoint() stability header to "Widest relative width (P10-P90): X%" for consistency with percentile interval terminology.
Link & Build Hygiene: Converted README links to absolute URLs, updated redirected URLs in NEWS.md, normalized CONTRIBUTING.md, and removed redundant data("colon") lookups in vignettes.

Testing & Quality Assurance

Regression Tests: Added tests verifying unadjusted systematic p-value searches, empirical p-value tail directions, and hazard_ratio metric extraction.
Tier Label Assertions: Added tests confirming tier_label returns "OVERLAPPING" or "CONSISTENT" and never legacy terms.
CRAN Test Throttling: Guarded high-replicate bootstrap routines and heavy systematic tests in test-workflow-integration.R and test-stability-metric.R with skip_on_cran().

OptSurvCutR 0.11.0

Bug Fixes

Stability Metric Denominator: Corrected summary.validate_cutpoint_result() to calculate relative confidence interval width against the predictor's empirical 10th–90th percentile range ($P_{90} - P_{10}$) by preserving userdata in validate_cutpoint(). This resolves an issue where reported widths were artificially inflated and Stability Tier 1 was unreachable.
Silent Fallback Removal: Removed arbitrary fallback denominators (bootstrap_distribution[, 1] and medians). Undefined data spreads or degenerate discrete predictors now return explicit diagnostic warnings rather than substituted metrics.
Single Cut-point Classification: Single-threshold models are now classified strictly on relative width (< 30% Tier 1, 30%–60% Tier 2, > 60% Tier 4), eliminating invalid Tier 3 assignments that require adjacent interval overlap.

API Changes & Enhancements

Programmatic Stability Access: Added a machine-readable $stability list to summary.validate_cutpoint_result() exposing tier classifications, per-cut relative widths, interval separation status, and data spread for automated batch workflows.
Data Retention: validate_cutpoint() now retains input analysis data in userdata, ensuring structural parity with find_cutpoint().

Documentation & Vignettes

Stability Tier Clarification: Clarified that the 4-tier matrix evaluates two independent diagnostic dimensions (interval separation and coordinate precision) rather than an ordinal rank.
Standards & Vignettes: Expanded @srrstats {G1.1} to detail methodological origins, re-rendered both clinical vignettes using corrected metrics, and updated README.md examples with the Mayo Clinic PBC cohort.
Console Diagnostics: Corrected typos and generalised console output across the systematic search engine to report actual candidate counts dynamically.

Testing & Quality Assurance

Metric Regression & Reachability: Added test-stability-metric.R to verify data inheritance, validate that single-cut models avoid Tier 3, and confirm that Tier 1 is empirically reachable on well-separated data.
Workflow Integration Tests: Added test-workflow-integration.R to ensure state and covariate preservation across the complete three-step pipeline (find_cutpoint_number() -> find_cutpoint() -> validate_cutpoint()).

OptSurvCutR 0.10.1

Documentation & Standards Compliance

Standards Compliance: Expanded @srrstats {G1.1} documentation to detail methodological foundations (BIC model selection and multivariable Cox optimization) and delineate scope from univariate single-split tools.
C++ Backend Alignment: Updated technical documentation to reflect pure Rcpp implementation in src/matrix_factory.cpp without external linear algebra dependencies.
Licensing & Governance: Added raw GNU GPL-3 text (LICENSE.md), linked CONTRIBUTING.md in README.md, and calibrated README claims around software reproducibility.
Vignettes & Examples: Refreshed package metadata, vignettes, and validation examples to align directly with the current public API.

API Changes & Code Quality

Plotting API Cleanup: Removed the obsolete trajectory plot route from the S3 plotting engine.
Namespace Isolation: Refactored the test suite across tests/testthat/ to eliminate all 40 unexported OptSurvCutR::: namespace calls.
Branch Test Coverage: Added targeted unit tests exercising parameter validations, edge conditions, and branching paths in find_cutpoint_number(), find_cutpoint(), and validate_cutpoint().
CRAN Verification: Achieved full compliance under R CMD check --as-cran with 0 errors, 0 warnings, and 0 notes.

Dependencies & Bug Fixes

Dependency Harmonization: Classified rgenoud under Suggests with defensive runtime namespace checks and updated user documentation.
Installation Fix: Corrected duplicated syntax in GitHub installation instructions (remotes::remotes:: to remotes::).

OptSurvCutR 0.10.0 (2026-06-30)

Documentation Updates

Updated package documentation and supporting materials for clarity and consistency.
Refreshed version references and release documentation.
Performed general project maintenance and housekeeping.

Note: This release contains no code changes, feature additions, bug fixes, or API modifications.

OptSurvCutR 0.9.9

Major Engine Enhancements

Integer Index-Space Mapping: Replaced the continuous floating-point search space with a discrete, bounded integer lattice mapped directly to sorted unique data row indices. This fundamentally shifts the engine math from an infinite decimal space to a finite spectrum of actual observations, eliminating micro-decimal overfitting and stochastic seed drift.
Hybrid Execution Routing: Upgraded threshold discovery to dynamically select the most efficient search engine. The package now defaults to a deterministic, exhaustive method = "systematic" grid sweep for lower dimensional profiles (1 or 2 cuts) to guarantee global maximum discovery with zero performance lag. For higher dimensions ($K \ge 3$), it seamlessly transitions to the evolutionary genetic algorithm (rgenoud backend).
Automated Proportional Hazards Diagnostics: Integrated a native 2-tier Schoenfeld residuals validation layer inside the core S3 summary() methods. The package automatically flags models violating the Cox proportional hazards assumption, distinguishing between Tier 1 (Proportional, Stable) and Tier 2 (Time-Varying, Dynamic Risk) cohorts.
Strict Structural Headroom Guardrails: Upgraded nmin cell-floor checking to calculate total available degrees of freedom prior to loop execution. When discrete data density collapses or drops below necessary cell floors, the engine throws clean UX alert messages and skips impossible configurations to prevent fatal R session crashes.

📊 Algorithmic Scaling Protocol

The table below outlines how OptSurvCutR automatically routes execution and scales its internal tuning parameters (pop.size and max.generations) based on target complexity ($K$ Cuts) and data structure:

| Target Complexity ($K$ Cuts) | Execution Method | Default Population Size (pop.size) | Default Search Lifespan (max.generations) | Optimisation Mechanics | | --- | --- | --- | --- | --- | | $K = 1$ Cut | systematic | N/A (Exhaustive Grid) | N/A (Exhaustive Grid) | Full 1D Coordinate Vector Sweep | | $K = 2$ Cuts | systematic | N/A (Exhaustive Grid) | N/A (Exhaustive Grid) | Full 2D Cross-Lattice Matrix Sweep | | $K = 3$ Cuts | genetic | 100 | 50 | 3D Index Hyper-Lattice Traversal | | $K = 4$ Cuts | genetic | 120 | 55 | 4D Hyper-Lattice Spatial Search | | $K = 5$ Cuts | genetic | 150 | 60 | 5D Multi-Epitope Surface Clustering | | $K = 6$ Cuts | genetic | 180 | 65 | 6D High-Dimensional Coordinate Scan | | $K = 7$ Cuts | genetic | 200 | 70 | 7D Ultra-Deep Hyper-Volume Optimization | | $K \ge 8$ Cuts | genetic | 250 | 80 | Complex Deep Lattice Cluster Optimisation | | Low-Density Data (Discrete) | systematic | N/A (Auto-collapsed) | N/A (Auto-collapsed) | Rigid Quantile Step Filtering / Cell Floor Defence | | Validation / Bootstrap Loop | Context Snapped | 10 (Streamlined default) | 2 (Streamlined default) | Accelerated Resampling Stability Assessment |

OptSurvCutR 0.9.8

New Core Features & Architecture

Optimal Cut Number Discovery (find_cutpoint_number): Introduced a new core function to mathematically determine the optimal number of cut-points (0 to 4) before running the genetic search. It supports model selection via Information Criteria (AIC, AICc, and BIC) to balance accuracy against complexity, preventing overfitting to sample-specific noise.
4-Tier Validation Stability System: Completely overhauled the output of validate_cutpoint(). The package now automatically evaluates both the Precision (Maximum CI Width) and Validity (Interval Overlap) of bootstrapped thresholds, categorising them into four distinct tiers: OPTIMAL (Tier 1), DISTINCT (Tier 2), CAUTION (Tier 3), and UNSTABLE (Tier 4).

Stability Tier Definitions

Modernised Console UI (cli Integration): Replaced standard cat() and print() outputs with the cli package. The package now features a highly readable, colour-coded, text-wrapping console UI for summaries, diagnostics, and tiered alerts, safely bypassing base R's 1,000-character warning limits.

Bare-Metal Low-Level Core Optimisation

Rcpp Integer-Assignment Factory (cpp_get_group_assignments): Migrated the deepest internal bottlenecks from high-level R loops to a native, compiled C++ backend via Rcpp. Instead of relying on R's single-threaded vector copying, a high-speed C++ loop now evaluates continuous variables against candidate thresholds and constructs group partitions directly at the hardware memory layer.
Elimination of findInterval and as.factor Bottlenecks: Replaced the native R group-allocation pipeline within the exhaustive grid search (.get_stat) and the evolutionary objective function (.obj). The engine now bypasses R's high-level object allocation layers entirely, cutting memory overhead significantly during heavy permutation loops and genetic generation iterations.
Vectorised tabulate() Constraint Evaluation: Replaced the expensive R table() and any(nlevels() < num_cuts) validation checks with fast C++ matrix array metrics and vectorised tabulate() calls. Subgroup sizes are now verified instantly using raw memory pointers before any survival formula is compiled, saving thousands of microsecond allocations per evaluation cycle.
Hardened S3 Attribute Anchoring: Implemented a protected S3 structural binding using the structure(..., class = "factor") paradigm to map the C++ integer vectors into formula-compliant categorical fields. This prevents R's internal object-replacement methods from stripping away structural attributes when dropped into the data pipeline, ensuring seamless, crash-free interoperability with survival::coxph and survival::survdiff.

Algorithmic Optimisation & Tie-Handling (Sparse Data Data-Paths)

Defensive Boundary Safety Buffering (The "Tie-Wedge"): Introduced an internal 2-patient mathematical tolerance window (nmin - 2) into both the systematic and genetic validation layers. This architectural guardrail resolves a structural vulnerability in global optimisation routines when evaluating heavily tied or highly zero-skewed continuous vectors. When a large percentage of observations share identical values (at the lower limit of detection or zero baselines), rigid group-size partitioning constraints become mathematically impossible to fulfil. The introduction of this tolerance window prevents strict gridlock rejections (-Inf / NA), allowing the core optimisation loops to safely navigate around data ties and locate valid optimal solutions.
Fail-Safe Compilation Guardrails: Added an environment tracking verification step to identify compilation or loading failures in the compiled C++ shared libraries at runtime. If an outdated server or obscure OS distribution blocks the binary namespace, the package prints a clear warning and automatically triggers a graceful degradation path (use_cpp = FALSE), falling back to the transparent, native R loop structures without throwing a fatal crash.

Major Performance Improvements & Memory Protections

C-Level Interval Math: Replaced cut() with findInterval(..., left.open = TRUE) within the fallback mathematical engines. This eliminates expensive string manipulations, making systematic grid searches faster while perfectly preserving the mathematical boundaries of the groups.
Genetic Algorithm Memoisation: Implemented a hash-based evaluation cache (eval_cache) inside the genetic algorithm wrapper. The algorithm now remembers previously evaluated cut-points and bypasses the survival::coxph model entirely for redundant guesses, drastically cutting computation time on large datasets with many generations.
Pre-Allocation for Genetic Search: Shifted text manipulation and formula generation outside the genetic algorithm loop. The algorithm now uses a pre-allocated data.frame template, eliminating thousands of redundant memory allocations.
OS-Optimised Bootstrapping: Upgraded the parallel processing backend in validate_cutpoint(). On Unix-based systems (Mac/Linux), the package now dynamically switches to FORK clusters (shared memory) instead of PSOCK. This drops data-transfer overhead to near-zero and drastically speeds up bootstrap validation.
Environment Memory-Isolation via Explicit Binding: Overhauled the internal execution layers to pass explicitly extracted atomic vector streams instead of raw, nested evaluations. This isolates the parent R session environments from leaking into parallel background threads, cutting down cumulative memory inflation during high-core execution.

Advanced Visualisation & Reporting (New Features)

Unified S3 Plotting Router: Overhauled the plot() method (plot.find_cutpoint()). It now supports full ... argument passthrough to survminer functions for deep customisation, and includes a return_data = TRUE "escape hatch" to extract the raw, stratified plotting data.
Schoenfeld Diagnostic Plots & 2-Tier Alert: Added type = "diagnostic" to automatically evaluate the proportional hazards assumption via survival::cox.zph() and plot the residuals. The summary() function now includes a 2-Tier diagnostic alert to warn users if predictive power shifts significantly over time, gracefully handling singular matrix edge cases.
Dashboard View: Added type = "all" to generate a comprehensive, stacked composite plot (powered by patchwork) showing both the predictor distribution and the resulting survival outcome curve in a single clinical snapshot.
Interactive Web Widgets: Introduced optsurv_interactive(), a wrapper function that converts any static OptSurvCutR plot into an interactive HTML widget via plotly (ideal for Vignettes and RMarkdown).
Clinical Aesthetics: Implemented theme_optsurv() and defaulted to colourblind-safe palettes (e.g., "nejm") to enforce a unified, publication-ready aesthetic across all outputs.

Bug Fixes & Edge Cases (find_cutpoint)

Dynamic Log-Likelihood Extraction: Fixed a bug where the p_value criterion would fail (or skip tests) when no covariates were provided. The null model log-likelihood is now extracted dynamically regardless of model length.
Degenerate Data Handling: Added a safeguard to check for zero-variance in the time column, ensuring the function safely returns NA rather than crashing on pathological datasets.
Dropped Coefficients: Added a check to safely return -Inf instead of NA if survival::coxph completely drops a coefficient (e.g., due to extreme collinearity) during a hazard_ratio search.

Structural Adjustments & Edge-Case Vulnerabilities (find_cutpoint_number)

Unadjusted Profile Likelihood Fallback Engine: Resolved a critical evolutionary calculation bottleneck inside .obj() when running unadjusted genetic searches (method = "genetic"). By adding an implicit zero-covariate structural detector, the engine now dynamically bypasses manual parameter init beta matrix arrays when no adjusters are present. This prevents survival::coxph(..., iter.max = 0) from crashing on bare categorical split factors, ensuring unadjusted model selection tables calculate 1 and 2 cuts perfectly.
Harden Nmin Evaluation Sequence: Re-ordered the parameter evaluation pipeline to calculate absolute patient sample splits (nmin_abs) prior to executing total data headroom matrix checks. This successfully stops proportional constraints (e.g., nmin = 0.25) from silently bypassing sample capacity filters.
Boundary Tie Headroom Margin: Built a 2-patient safety headroom filter into the information criteria data-capacity logic. This automatically intercepts brittle or impossible search spaces (such as requesting 3 cuts on 580 patients with a strict 25% allocation limit) and down-caps or exits gracefully before triggering genetic algorithm failures.

Stability & Parallel Processing (validate_cutpoint)

CRAN-Safe Core Detector: Built an environment check (Sys.getenv("_R_CHECK_LIMIT_CORES_")) into the core architecture. The package now detects when it is running on CRAN's testing servers and automatically throttles itself to 2 cores to prevent rejection, while allowing real users to utilise maximum CPU power.
Parallel Variable-Name Scope Isolation: Resolved a critical parallel clustering crash (argument "predictor" is missing, with no default) that occurred inside .run_permutations() during high-throughput bootstrap resampling. The signature now maps explicit variable text strings alongside the split memory streams, ensuring independent worker processes (%dopar%) can parse formulas cleanly across separate CPU nodes.
Data-Stream Alignment Fix for Scoped Models: Fixed a dataset scope conflict (argument "data" is missing, with no default) inside the parallel foreach environment. By binding the structural data components directly within the function parameter signature rather than relying on global environmental evaluations, parallel worker environments successfully execute deep iterations across any operating system without variable scope dropouts.
Renamed Predictor Collision Handling: Fixed a tracking bug inside summary.find_cutpoint_number_result where the function printed "Unknown" for the main predictor variable under specific covariate-adjusted models. The S3 summary framework now tracks original column metadata across all renaming phases to provide pristine diagnostic dashboards for clinical research reporting.
Parallel Closure Fix (... arguments): Fixed a critical bug where running validate_cutpoint with n_cores > 1 would instantly fail if extra arguments (like max.generations or pop.size) were passed to the foreach loop.
Console Spam Prevention: Bootstrapping with replacement naturally creates tied survival times, which can trigger expected model convergence warnings. Parallel model fits are now wrapped in suppressWarnings() to prevent these benign warnings from flooding the user's console and breaking the progress bar.
Namespace Safety: Refactored the parallel execution block to reliably call the exported find_cutpoint() wrapper. This guarantees that parallel worker nodes on any operating system can successfully locate the internal evaluation functions without namespace crashes.
S3 Summary Parameter Printing Fix: Resolved an unescaped string and operator evaluation syntax error within the cli::cli_bullets parameter tracking block inside summary.find_cutpoint_number_result. All named bullet outputs are now tightly mapped to explicitly bounded, single-quoted parameters ("*" =), guaranteeing clean console rendering.

OptSurvCutR 0.2.1

CRAN Compliance & Quality of Life Improvements

This patch release addresses CRAN reviewer feedback and polishes the package's console behaviour and visual branding.

Enhanced Console Control: Replaced all informational print() and cat() statements with message() in the core functions (find_cutpoint(), find_cutpoint_number(), and validate_cutpoint()). Users can now easily silence progress text by wrapping functions in suppressMessages().
Cleaned Return Behaviors: Removed forced print() calls from the end of the main S3 calculation functions. Results now return silently when assigned to a variable, while preserving formatted output when called directly.
DESCRIPTION File Formatting: Removed single quotes around function and package names in the DESCRIPTION file to satisfy CRAN automated parsers.
Official Branding: Added the official OptSurvCutR hex logo! The logo is now bundled within the package (man/figures/logo.png) and fully integrated into the GitHub README and pkgdown website configuration.

OptSurvCutR 0.2.0

DOCUMENTATION & STANDARDS

Initial CRAN submission.
Updated the package structure (minor) to meet the submission requirement.

OptSurvCutR 0.1.9.3

DOCUMENTATION & STANDARDS

Graphical Abstract: Added the new graphical abstract to the image/ folder for inclusion in the README.md. OptSurvCutR Graphical Abstract

Instruction Page (README.md): Updated the main package repository instructions.

COMMUNITY & OUTREACH

Presentations: Presented at FOSDEM 2026 in the Bioinformatics & Computational Biology DevRoom in Brussels, Belgium. View lightning talk details

Presentations: Presented at R!SK 2026 (February 18–19, 2026). This 100% online conference focuses on evaluating, measuring, and mitigating risk across diverse industries including healthcare, finance, and insurance. The event featured deep content sessions and live Q&A interactions. View presentation abstract

OptSurvCutR 0.1.9.2

ROPENSCI REVIEW UPDATES (ITERATION 2)

BREAKING CHANGES

Renamed Functions: plot_optimization_curve() $\to$ plot_optimisation_curve() (British English) and plot_schoenfeld() $\to$ plot_cutpoint_residuals() (Namespace conflict).
Renamed Argument: maxiter is now max.generations in genetic algorithm functions to match rgenoud.

IMPROVEMENTS

Explicit Parameters: Exposed pop.size and max.generations as explicit arguments in find_cutpoint() and find_cutpoint_number().
Consistent Logic: All functions now use floor() for nmin calculation to ensure identical sample size handling.
Better Validation: validate_cutpoint() now accepts nmin as a proportion and issues an informative message when using the default 90% buffer (Standard G2.10).
Internal Cleanup: Removed export of helper operator %||%.

DOCUMENTATION & STANDARDS

British English: Standardised all functions and documentation (e.g., "optimise", "summarise").
Standards Compliance: Audited and updated all @srrstats tags; moved non-applicable standards to R/OptSurvCutR-package.R.
Testing: Added tests for new genetic parameters and updated snapshot tests for S3 methods.

OptSurvCutR 0.1.9

REFACTORING & MAINTENANCE

Simplified Parallel Interface: The use_parallel argument was removed from validate_cutpoint(). Parallel execution is now controlled exclusively by the n_cores argument (n_cores = 1 for sequential, n_cores > 1 for parallel).
Consolidated Validation Logic: A new internal helper .validate_event_column() was created in R/utils-helpers.R to centralise the logic for checking that an event column is numeric and contains only 0s and 1s. Both find_cutpoint_number() and the internal helper .validate_data_conditions() (also in R/utils-helpers.R) were updated to call this function, eliminating duplicated code.
Simplified Parallel Code: In validate_cutpoint(), the brittle functions_to_export block was removed. The function now correctly relies on the .packages = "OptSurvCutR" argument in the foreach loop, making it easier to maintain.

BUG FIXES

Fixed Parallel Reproducibility: A bug in validate_cutpoint() that prevented true reproducibility for parallel runs (n_cores > 1) was fixed. The function now checks for and registers the {doRNG} package when a seed is provided, ensuring results are identical regardless of the number of cores used. The incorrect set.seed(i) call inside the foreach loop was removed.
Improved S3 Method Robustness: The summary.find_cutpoint_number_result() S3 method was updated to robustly handle NULL values in the object$parameters list (e.g., method = NULL). This prevents potential errors if a result object is created manually or improperly and aligns its behaviour with the print() method.

DOCUMENTATION

Clarified Log-Rank Test: The documentation for find_cutpoint() was updated to clarify that when covariates are provided, the "logrank" criterion is automatically generalised to the more appropriate Cox score test.

IMPROVEMENTS

Test Coverage: Increased test coverage to 88.5% with new unit tests for parallel reproducibility, S3 method edge cases, and internal validation helpers.

Planned: An rOpenSci submission is planned for review.
Planned: A JOSS submission is planned post-rOpenSci review.

OptSurvCutR 0.1.8

CRITICAL BUG FIXES

Parallel Validation: Fixed a critical bug where validate_cutpoint(use_parallel = TRUE) would fail. This was caused by helper functions not being exported to the parallel workers.
Event Column Validation: Fixed a major bug where non-numeric outcome_event data (e.g., "0:LIVING") caused silent failures. The functions now "fail-fast" with an error, validating the column is numeric with only 0s and 1s.
Genetic Algorithm Reporting: Fixed a bug where method = "genetic" would report a failure (-Inf) as a successful result. The functions now correctly check for the failure signal and return NA.

NEW FEATURES

G3.1a Compliance — Schoenfeld Residual Diagnostics: Added plot_diagnostics() to generate publication-ready Schoenfeld residual plots, assessing the proportional hazards (PH) assumption.

IMPROVEMENTS

Code Quality (Refactoring): Refactored find_cutpoint() to resolve "high cyclomatic complexity" NOTEs by moving validation logic to internal helper functions.
Test Coverage: Increased test coverage by adding new unit tests for error conditions, edge cases, and validation logic.
rOpenSci/pkgcheck Compliance:
- Added examples to all exported functions.
- Added @srrstats tags to satisfy multi-directory requirements.
R CMD check Compliance: Addressed all ERRORs, WARNINGs, and NOTEs:
- Added inst/WORDLIST, _PACKAGE documentation, and fixed empty Rd sections.
- Added codemeta.json to .Rbuildignore.
Code Style:
- Reformatted code to follow Tidyverse Style Guide principles (e.g., <- for assignment, " for strings, consistent spacing around operators).
- Strictly enforced an 80-character maximum line length for all code, comments, and documentation.
- Made Roxygen documentation, inline comments, and user-facing messages more concise.
- Replaced sapply() with type-safe vapply() in S3 methods to prevent potential bugs.
Internal Data: The crc_virome dataset's status column was corrected to be numeric 0/1 to match documentation and new validation rules.

OptSurvCutR 0.1.7

NEW FEATURES

Covariate Adjustment Added: Both find_cutpoint() (for method = "systematic" and method = "genetic") and find_cutpoint_number() now support covariate adjustment via the covariates argument. This allows finding optimal cut-points and determining the optimal number of groups while accounting for potential confounders, providing a more robust assessment of a biomarker's independent prognostic value.

IMPROVEMENTS

Major Performance Optimisation: Significantly optimised performance in find_cutpoint() for criterion = "hazard_ratio" and criterion = "p_value" (both systematic and genetic methods). This was achieved by removing computationally expensive summary() calls, extracting coefficients and statistics directly from model objects, and using a fast, manual Likelihood Ratio Test for p-value calculation.
Simplified Parallelism: Removed internal parallel processing (use_parallel argument) from find_cutpoint and find_cutpoint_number systematic search. This prevents potential issues with nested parallel calls and relies on standard external parallelisation approaches, such as the explicit parallel loop within validate_cutpoint.
Test Suite Overhaul: Revamped the entire testthat suite for improved reliability and robustness. Replaced brittle expect_snapshot() tests with more stable checks like expect_output(), expect_s3_class(), and specific value comparisons. Corrected logic for error and warning expectations and improved mocking for dependency checks. Code coverage increased significantly (for example, to ~86%).
User-Friendly rgenoud Check: Added clear, informative error messages using cli in find_cutpoint() and find_cutpoint_number() that trigger immediately if method = "genetic" is requested but the suggested rgenoud package is not installed, guiding the user on how to install it.
Dependency Management: Moved optional dependencies broom (for plotting) and withr (for testing) from Imports to Suggests in the DESCRIPTION file, making the core package installation lighter. Removed unused magrittr import.
Simplified Evidence Labels: Renamed evidence labels in find_cutpoint_number() results for brevity (for example, "Substantial support" -> "Substantial").
Code Maintainability: Centralised all utils::globalVariables definitions into globals.R to resolve R CMD check NOTEs and improve clarity. Removed redundant code.

BUG FIXES

quiet = TRUE Message Fix: Fixed a critical bug where find_cutpoint() and find_cutpoint_number() would fail silently (no console message) when quiet = TRUE was set. Failure messages are now always printed to the console via internal helpers, regardless of the quiet setting, improving user feedback on errors.
Genetic Algorithm Edge Cases: Added more robust input validation and handling within the internal .run_genetic_search() function to gracefully manage edge cases like insufficient data variability or non-finite predictor ranges, preventing downstream errors and cryptic warnings.
Genetic Algorithm Monitor: Fixed the internal monitoring function used by the genetic algorithm (rgenoud::genoud) to correctly respect the print.level argument (controlled indirectly via user functions), ensuring progress updates are displayed or suppressed as intended.
NAMESPACE Fix (stats::): Resolved NAMESPACE errors and related test failures by adding explicit stats:: calls where needed (for example, for stats::quantile, stats::sd, stats::pchisq) and ensuring correct regeneration of the NAMESPACE file via devtools::document().
foreach NOTE Fix: Resolved R CMD check NOTE regarding "no visible binding for global".

IMPROVEMENTS

Planned: An rOpenSci submission is planned for review.
Planned: A JOSS submission is planned post-rOpenSci review.

OptSurvCutR 0.1.6

NEW FEATURES

Added a vignette demonstrating the use of find_cutpoint() and validate_cutpoint() with TCGA virome data (for example, Alphapapillomavirus as a predictor), guiding users through cut-point optimisation and stability assessment for survival analysis.
Introduced comprehensive unit tests using testthat, covering core functions (find_cutpoint(), find_cutpoint_number(), validate_cutpoint()) and edge cases like missing data or small sample sizes, with code coverage reporting via covr to ensure reliability (>80% coverage).

IMPROVEMENTS

Optimised the genetic algorithm in find_cutpoint() by implementing adaptive pop.size (for example, 50 for num_cuts = 1) and max.generations (for example, 75), reducing runtime by 20–50% for survival datasets while maintaining accuracy for optimal cut-point selection.
Enhanced error messages in validate_cutpoint() to provide specific feedback on bootstrap validation failures, such as insufficient sample sizes or non-converging coxph models, improving user debugging experience.
Added a pkgdown GitHub Action to automatically build a package website, improving documentation accessibility, and updated README with badges for build status and code coverage to signal package reliability.
Updated DESCRIPTION with corrected URLs, dependency versions, and regenerated Rd files for consistent documentation across all functions.

BUG FIXES

Fixed NA handling in find_cutpoint() to robustly process survival datasets with missing predictor values, preventing errors in coxph or survdiff model fitting for real-world data like TCGA virome datasets.

OptSurvCutR 0.1.5

IMPROVEMENTS

Updated core functions (for example, find_cutpoint(), find_cutpoint_number()) with improved numerical stability and accuracy for survival model fitting, particularly for genetic algorithm convergence in high-dimensional predictors.

BUG FIXES

Fixed bugs in script handling and input validation, improving reliability for edge cases like small datasets or constant predictors in survival analysis.
Reverted prior bug fixes to prevent potential regressions, ensuring stable behaviour in validate_cutpoint() during bootstrap validation runs.

OptSurvCutR 0.1.0

NEW FEATURES

Initial release of OptSurvCutR for optimising cut-points in survival analysis.
Added find_cutpoint() to identify optimal cut-points for continuous predictors using systematic or genetic algorithms (via rgenoud) with log-rank, p-value, or hazard-ratio criteria.
Added find_cutpoint_number() to select the optimal number of cut-points using AIC, AICc, or BIC.
Added validate_cutpoint() for bootstrap-based stability assessment of cut-points.
Supports survival models via survival::coxph and survival::survdiff.
Includes example usage with simulated churn data, adaptable to TCGA virome datasets (for example, Alphapapillomavirus).