The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.
OptSurvCutR (Optimal
Survival Cut-points
R) provides a rigorous, reproducible, and
rOpenSci-compliant framework for discovering the optimal number and
location of patient stratification thresholds in time-to-event
(survival) data. Designed specifically for continuous predictors (such
as gene expression measurements, microbiome abundance, or clinical
biomarkers), this package moves beyond arbitrary median splits to
deliver fully data-driven, covariate-adjusted
stratification.
We have significantly overhauled the validation and diagnostic engines to ensure your discovered thresholds are mathematically stable, rOpenSci-compliant, and ready for publication:
Integer Index-Space Mapping: Replaced continuous floating-point search spaces with a discrete, bounded integer lattice mapped directly to sorted unique data indices. This shifts the engine mathematics from an infinite decimal space to a finite spectrum of actual observations, eliminating micro-decimal overfitting and stochastic seed drift.
The Four-Tier Stability Assessment: Bootstrap validation now automatically grades thresholds into four distinct tiers (Optimal, Distinct, Caution, and Unstable) based on confidence interval width and overlap metrics.
Automated Schoenfeld Diagnostics: The package now evaluates time-varying effects natively during the optimisation phase to ensure your thresholds do not violate the proportional hazards assumption.
Enhanced Parameter Controls: Fine-tune the
underlying genetic algorithm using minimum group size
(nmin) wedges and soft boundaries to rescue unstable
thresholds and control for overfitting.
Continuous 2D Contour Validation Landscapes: Added native S3 routing support to project complex, multi-dimensional bootstrap distribution horizons onto smooth contour peaks.
| Feature | Benefit |
|---|---|
| Optimal number of cuts | Uses AIC, AICc, or BIC to mathematically select between \(0\) and \(k\) cut-points. |
| Covariate adjustment | Demonstrates independent prognostic value by controlling for clinical confounders. |
| Four-tier bootstrap validation | Generates 95% confidence intervals and automated stability grading for thresholds. |
| Schoenfeld diagnostics | Features a two-tier warning system to verify proportional hazards assumptions. |
| Flexible search engines | Supports a deterministic systematic grid
or a multithreaded Genetic Algorithm (rgenoud). |
| Publication-ready plots | Renders Kaplan–Meier curves, distribution splits, forest plots, and 2D topology surfaces. |
You can install the development version of OptSurvCutR
directly from GitHub. Note that the genetic algorithm optimisation
(method = "genetic") requires the rgenoud
package, which should be installed separately from CRAN if you plan to
search for multiple cut-points.
# Core dependencies
install.packages(c("remotes", "survival"))
# Optional but highly recommended for multi-cut genetic optimisation
install.packages("rgenoud")
# Install the package from GitHub
remotes::remotes::install_github("paytonyau/OptSurvCutR")library(OptSurvCutR)
library(survival)
library(dplyr)
# Generate a reproducible, synthetic survival dataset
set.seed(123)
n <- 200
crc <- tibble(
abundance = rnorm(n, mean = 5, sd = 2),
age = rnorm(n, mean = 60, sd = 10),
# Generate survival times influenced by biomarker abundance
time = rexp(n, rate = 0.05 * exp(0.3 * (abundance > 5.5) + 0.02 * age)),
event = sample(c(0, 1), n, replace = TRUE, prob = c(0.3, 0.7))
) %>% filter(time > 0)
# Step 1: Determine the optimal number of cut-points
num_res <- find_cutpoint_number(
data = crc, predictor = "abundance",
outcome_time = "time", outcome_event = "event",
method = "genetic", criterion = "BIC",
max_cuts = 3, nmin = 0.25, seed = 123
)
summary(num_res)
# Step 2: Find the precise cut-point locations
cut_res <- find_cutpoint(
data = crc, predictor = "abundance",
outcome_time = "time", outcome_event = "event",
method = "genetic", criterion = "logrank",
num_cuts = num_res$optimal_num_cuts, # Dynamically pass the result from Step 1
nmin = 0.275, # Fine-tuned for stability
n_perm = 50, n_cores = 2, seed = 123
)
summary(cut_res) # Automatically reports Hazard Ratios & Schoenfeld Diagnostics!
# Step 3: Validate threshold stability with bootstrapping
val_res <- validate_cutpoint(
cutpoint_result = cut_res,
num_replicates = 150, n_cores = 2, seed = 123
)
summary(val_res) # Automatically grades threshold stability (Tiers 1-4)!
# Step 4: Visualise outcomes via native S3 plot routes
plot(cut_res, type = "distribution") # Continuous Predictor Density Split Map
plot(cut_res, type = "outcome") # Premium Custom Kaplan-Meier Survival Curves
plot(cut_res, type = "forest") # Hazard Ratio Forest Plot with Cohort Sample Sizes
plot(cut_res, type = "diagnostic") # Schoenfeld Residual Proportional Hazards Check
plot_validation(val_res, focus_cuts = c(1, 2)) # 2D Contour Elevation Stability TopologyOptSurvCutR establishes a structured, three-step
workflow for cut-point analysis:
find_cutpoint_number(): Identifies the statistically
optimal number of thresholds using information criteria.find_cutpoint(): Localises exact cut-point coordinates
via systematic or genetic search, and reports Schoenfeld
diagnostics.validate_cutpoint(): Evaluates threshold stability
using bootstrap resampling and assigns an automated four-tier stability
grade.browseVignettes("OptSurvCutR") within your R session to
access complete walk-throughs.vignettes/troubleshooting.Rmd source path.@article{yau2025optsurvcutr,
author = {Yau, Payton T. O.},
title = {OptSurvCutR: Validated Cut-point Selection for Survival Analysis},
year = {2025},
doi = {10.1101/2025.10.08.681246},
publisher = {Cold Spring Harbor Laboratory},
journal = {bioRxiv},
url = {[https://www.biorxiv.org/content/10.1101/2025.10.08.681246](https://www.biorxiv.org/content/10.1101/2025.10.08.681246)}
}Licensed under the GPL-3 License.
For questions, feature suggestions, or bug reports, please open an issue tracking ticket: https://github.com/paytonyau/OptSurvCutR/issues
These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.