R/survalis-package.R

In survalis: Interpretable Survival Machine Learning Framework

# R/survalis-package.R

#' survalis: Interpretable Survival Machine Learning
#'
#' survalis provides a unified interface for fitting, predicting, evaluating,
#' tuning, comparing, interpreting and standardising survival machine-learning
#' models across 24 learners.
#'
#' @section The seven verbs:
#' The recommended interface, consistent with the \pkg{funcml} package:
#' \describe{
#'   \item{[fit()]}{fit a learner by id, returning a `survalis_fit`.}
#'   \item{[predict()]}{typed predictions on a recorded time grid
#'     (`"survival"`, `"risk"`, `"chf"`, `"hazard"`, `"rmst"`, `"quantile"`,
#'     `"median"`).}
#'   \item{[evaluate()]}{resampled performance for a fit or a formula.}
#'   \item{[tune()]}{grid search, returning the refit best model.}
#'   \item{[compare()]}{paired multi-model leaderboard on shared folds.}
#'   \item{[interpret()]}{one entry point to the explanation methods.}
#'   \item{[estimate()]}{standardised binary-treatment contrast by
#'     G-computation.}
#' }
#' Resampling is described by [cv()], [holdout()], [groupcv()] and
#' [bootstrap()]. Discover components with [listlearners()],
#' [listmetrics()] and [listmethods()].
#' Custom learners plug into every verb as `model = list(fit = , predict = )`;
#' see [fit()].
#'
#' @keywords internal
"_PACKAGE"



# Silence R CMD check NOTES for NSE variables used in dplyr/ggplot2 code
if (getRversion() >= "2.15.1") {
  utils::globalVariables(c(".", "effect", "observed_surv", "phi"))
}


#' Re-export Surv from survival
#'
#' @examples
#' Surv(c(5, 8, 12), c(1, 0, 1))
#' @importFrom survival Surv
#' @export
survival::Surv




#' @importFrom survival Surv survfit coxph aareg concordance
#' @importFrom flexsurv flexsurvreg
#' @importFrom randomForestSRC rfsrc
#' @importFrom partykit cforest
#' @importFrom timereg aalen cox.aalen
#' @importFrom mboost blackboost
#' @importFrom BART surv.bart
#' @importFrom xgboost xgb.train xgb.cv xgb.DMatrix
#' @importFrom CoxBoost CoxBoost cv.CoxBoost
#'
#' @importFrom stats model.frame model.matrix model.response delete.response
#'   terms formula update as.formula na.omit na.exclude na.pass predict
#'   runif rnorm rexp pnorm qnorm plogis sd quantile approx setNames
#'   coef predict.lm residuals lm glm binomial
#'
#' @importFrom utils tail head combn
#'
#' @importFrom ggplot2 ggplot aes geom_line geom_point geom_bar geom_histogram
#'   geom_boxplot labs theme_minimal theme element_text facet_wrap
#'   scale_color_manual scale_fill_manual
#'
#' @importFrom rlang .data enquo sym
#'
#' @importFrom parallel detectCores makeCluster stopCluster
#' @importFrom stats aggregate dist reorder reshape time var
#' @importFrom utils capture.output getFromNamespace
#' @importFrom ggplot2 geom_jitter geom_smooth geom_errorbar geom_abline coord_fixed coord_flip coord_cartesian geom_col
#' @importFrom stats pnorm
#' @importFrom pracma trapz
#' @importFrom gower gower_dist
#' @importFrom glmnet glmnet
#' @importFrom ggplot2 ggplot aes geom_line geom_point geom_col
#' @importFrom ggplot2 geom_errorbar geom_jitter geom_abline geom_smooth geom_vline geom_hline
#' @importFrom ggplot2 labs theme_minimal coord_flip coord_fixed guides guide_legend
#' @importFrom ggplot2 position_dodge stat_summary scale_fill_manual scale_color_discrete
#' @importFrom ggplot2 geom_tile
#' @importFrom glue glue


NULL




utils::globalVariables(c(
  # tidyselect / dplyr
  "metric","value","n","se","learner","scaled_importance","weight",
  "feature","feature1","feature2","feature_label","feature_value",
  "surv_prob","mean_pred_surv","lower_ci","upper_ci","calib_result",
  "bin","direction","count","time","id","outer_fold",
  # data.table-esque
  ".id","lower","upper","n.risk","strata","surv",
  # others seen in notes
  "splits","ale","integrated_ale","type","change_label","hjust",
  # new in 1.1.0: dca_survmat/roc_survmat/plot_rmst/plot_shap_beeswarm
  "threshold","net_benefit","strategy","specificity","sensitivity",
  "tau","estimate","lo","hi","scaled_value",
  # new: compute_survcluster/plot_survcluster
  "survival","subject","cluster",
  # new in 1.3.0: verb result plot methods
  "model","arm"
))