--- title: "Moving from survalis 1.x to the seven verbs" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Moving from survalis 1.x to the seven verbs} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set(collapse = TRUE, comment = "#>") run <- requireNamespace("ranger", quietly = TRUE) ``` survalis 2.0.0 exports seven verbs and nothing that duplicates them: `fit()`, `predict()`, `evaluate()`, `tune()`, `compare()`, `interpret()` and `estimate()`. Around them sit the resampling specs (`cv()`, `holdout()`, `groupcv()`, `bootstrap()`) and three lookups that give the valid ids (`listlearners()`, `listmetrics()`, `listmethods()`). The 1.x per-learner functions (`fit_ranger()`, `predict_ranger()`, `tune_ranger()`, ...) and the helper families (`cv_*()`, `benchmark*()`, `compute_*()`, `plot_*()`, `*_survmat()`) are no longer exported. Each one maps to a verb argument: the learner goes in `model`, the metric in `metrics`, the explanation in `method`, the output scale in `type`, and every result has a `plot()` method. ## The mapping ### Fitting and prediction | 1.x | 2.0 | |---|---| | `fit_ranger(f, data, num.trees = 500)` | `fit(f, data, "ranger", spec = list(num.trees = 500))` | | `predict_ranger(m, nd, times)` | `predict(m, nd, times)` | | `survmat_to_rmst(S, times, tau)` | `predict(m, nd, times, type = "rmst", tau = ...)` | | `survmat_to_quantile(S, times, p)` | `predict(m, nd, times, type = "quantile", probs = p)` or `type = "median"` | | `survmat_to_chf(S)` | `predict(m, nd, times, type = "chf")` | | `survmat_to_haz(S, times)` | `predict(m, nd, times, type = "hazard")` | | `fit_survmetalearner(...)` | `fit(f, data, "survmetalearner", spec = list(learners = ...))` | | a hand-written `fit_fun` / `pred_fun` pair | `fit(f, data, model = list(fit = , predict = ))` | ### Evaluation | 1.x | 2.0 | |---|---| | `cv_survlearner(f, data, fit_fun, pred_fun, times, folds = 5)` | `evaluate(f, data, "ranger", times = ..., resampling = cv(5))` | | `score_survmodel(m, times, metrics)` | `evaluate(m, times = ..., metrics = ...)` | | `cv_summary(res)` | `summary(evaluate(...))` | | `cv_plot(res)` | `plot(evaluate(...))` | | `cindex_survmat(y, S, t)`, `ibs_survmat(y, S, times)`, `brier(...)`, `auc_survmat()`, `iae_survmat()`, `ise_survmat()`, `ece_survmat()` | `evaluate(S, y = y, metrics = c("cindex", "ibs", ...))` | | predict on a test set, then a metric helper | `evaluate(m, newdata = test, times = ...)` | | `roc_survmat()` + `plot_roc()` | `plot(interpret(m, "roc", newdata = test, eval_time = t))` | | `dca_survmat()` + `plot_dca()` | `plot(interpret(m, "dca", newdata = test, eval_time = t))` | ### Tuning and comparison | 1.x | 2.0 | |---|---| | `tune_ranger(f, data, times, param_grid, refit_best = TRUE)` | `tune(f, data, "ranger", grid = param_grid, times = ...)` | | `list_tunable_survlearners()` | `listlearners(has_tune = TRUE)` | | `benchmark(f, data, learners, times)` | `compare(f, data, models = learners, times = ...)` | | `benchmark_default_survlearners(...)` | `compare(...)` | | `benchmark_tuned_survlearners(...)` | `compare(..., tune = TRUE)` | | `summarise_benchmark()`, `best_survlearner()` | `print()` or `summary()` a `compare()` result | | `plot_benchmark()` | `plot(compare(...))` | ### Interpretation and causal contrasts | 1.x | 2.0 | |---|---| | `compute_pdp(m, data, "karno", times)` + `plot_pdp()` | `plot(interpret(m, "pdp", feature = "karno", times = ...))` | | `compute_ale()` + `plot_ale()` | `interpret(m, "ale", feature = ...)` | | `compute_shap()` + `plot_shap()` | `interpret(m, "shap", newdata = nd, ...)` | | `compute_shap_matrix()` + `plot_shap_beeswarm()` | `interpret(m, "shap_matrix", newdata = nd, ...)` | | `compute_varimp()` + `plot_varimp()` | `interpret(m, "varimp", ...)` | | `compute_interactions()` + `plot_interactions()` | `interpret(m, "interaction", ...)` | | `compute_counterfactual()` | `interpret(m, "counterfactual", target_time = ...)` | | `compute_surrogate()`, `compute_tree_surrogate()` | `interpret(m, "surrogate", ...)`, `interpret(m, "tree_surrogate", ...)` | | `compute_calibration()` + `plot_calibration()` | `interpret(m, "calibration", eval_time = ...)` | | `compute_survcluster()` + `plot_survcluster()` | `interpret(m, "survcluster", K = ...)` | | `estimate_rmst(m, data, tau, times, trt_col = "trt")` + `plot_rmst()` | `estimate(f, data, "", treatment = "trt", tau = ...)` | ### Kaplan-Meier curves `plot_survcurve(f, data)` becomes `kmplot(f, data)`, which draws Kaplan-Meier survival curves, or risk curves with `type = "risk"`, over a number-at-risk table. ### Removed without a replacement * `screen_fdr()`: use the `"selectcox"` or `"glmnet"` learners, which select variables while fitting. * `theme_survalis()`, `scale_color_survalis()` and `scale_fill_survalis()`: survalis plots still use this style internally. ## Side by side ```{r, eval = run} library(survalis) f <- Surv(time, status) ~ age + karno + celltype m <- fit(f, veteran, "ranger", spec = list(num.trees = 200), seed = 1) round(as.matrix(predict(m, veteran[1:3, ], times = c(90, 180))), 3) predict(m, veteran[1:3, ], times = c(90, 180), type = "rmst") ``` A learner of your own replaces the 1.x `fit_fun` / `pred_fun` arguments. Its `predict` returns one row per subject and one column per time: ```{r} expo <- list( name = "exponential", fit = function(formula, data, ...) survival::survreg(formula, data, dist = "exponential"), predict = function(object, newdata, times) { rate <- 1 / predict(object, newdata, type = "response") exp(-outer(rate, times)) } ) evaluate(Surv(time, status) ~ age + karno, veteran, model = expo, times = c(90, 180), resampling = cv(3, seed = 1)) ``` ## Other changes on purpose * **`predict()` returns a survival matrix** for the curve types: an `n x length(times)` matrix with the grid in `attr(x, "times")` and column names `"t=