model spec for survival_reg

Author: hfrick

R/survival_reg.R

@@ -0,0 +1,129 @@
+#' General Interface for Parametric Survival Models
+#'
+#' `survival_reg()` is a way to generate a _specification_ of a model
+#'  before fitting and allows the model to be created using
+#'  R. The main argument for the
+#'  model is:
+#' \itemize{
+#'   \item \code{dist}: The probability distribution of the outcome.
+#' }
+#' This argument is converted to its specific names at the
+#'  time that the model is fit. Other options and argument can be
+#'  set using `set_engine()`. If left to its default
+#'  here (`NULL`), the value is taken from the underlying model
+#'  functions.
+#'
+#' @inheritParams boost_tree
+#' @param mode A single character string for the type of model.
+#'  The only possible value for this model is "censored regression".
+#' @param dist A character string for the outcome distribution. "weibull" is
+#'  the default.
+#' @details
+#' The data given to the function are not saved and are only used
+#' to determine the _mode_ of the model. For `survival_reg()`,the
+#' mode will always be "censored regression".
+#'
+#' Since survival models typically involve censoring (and require the use of
+#' [survival::Surv()] objects), the [fit()] function will require that the
+#' survival model be specified via the formula interface.
+#'
+#' Also, for the `flexsurv::flexsurvfit` engine, the typical
+#'  `strata` function cannot be used. To achieve the same effect,
+#'  the extra parameter roles can be used (as described above).
+#'
+#' The model can be created using the `fit()` function using the
+#'  following _engines_:
+#' \itemize{
+#' \item \pkg{R}:  `"flexsurv"`, `"survival"` (the default)
+#' }
+#'
+#' @seealso [fit()], [survival::Surv()]
+#' @references Jackson, C. (2016). `flexsurv`: A Platform for Parametric Survival
+#'  Modeling in R. _Journal of Statistical Software_, 70(8), 1 - 33.
+#' @examples
+#' survival_reg()
+#' # Parameters can be represented by a placeholder:
+#' survival_reg(dist = varying())
+#'
+#' @export
+survival_reg <- function(mode = "censored regression", dist = NULL) {
+
+  args <- list(
+    dist = enquo(dist)
+  )
+
+  new_model_spec(
+    "survival_reg",
+    args = args,
+    eng_args = NULL,
+    mode = mode,
+    method = NULL,
+    engine = NULL
+  )
+}
+
+#' @export
+print.survival_reg <- function(x, ...) {
+  cat("Parametric Survival Regression Model Specification (", x$mode, ")\n\n", sep = "")
+  model_printer(x, ...)
+
+  if (!is.null(x$method$fit$args)) {
+    cat("Model fit template:\n")
+    print(show_call(x))
+  }
+
+  invisible(x)
+}
+
+# ------------------------------------------------------------------------------
+
+#' Update a Parametric Survival Regression Specification
+#'
+#' If parameters need to be modified, this function can be used
+#'  in lieu of recreating the object from scratch.
+#'
+#' @inheritParams update.boost_tree
+#' @param object A survival regression model specification.
+#' @examples
+#' model <- survival_reg(dist = "weibull")
+#' model
+#' update(model, dist = "lnorm")
+#' @method update survival_reg
+#' @rdname survival_reg
+#' @export
+update.survival_reg <- function(object, parameters = NULL, dist = NULL, fresh = FALSE, ...) {
+
+  eng_args <- update_engine_parameters(object$eng_args, ...)
+
+  if (!is.null(parameters)) {
+    parameters <- check_final_param(parameters)
+  }
+
+  args <- list(
+    dist = enquo(dist)
+  )
+
+  args <- update_main_parameters(args, parameters)
+
+  if (fresh) {
+    object$args <- args
+    object$eng_args <- eng_args
+  } else {
+    null_args <- map_lgl(args, null_value)
+    if (any(null_args))
+      args <- args[!null_args]
+    if (length(args) > 0)
+      object$args[names(args)] <- args
+    if (length(eng_args) > 0)
+      object$eng_args[names(eng_args)] <- eng_args
+  }
+
+  new_model_spec(
+    "survival_reg",
+    args = object$args,
+    eng_args = object$eng_args,
+    mode = object$mode,
+    method = NULL,
+    engine = object$engine
+  )
+}

R/survival_reg_data.R

@@ -0,0 +1,7 @@
+
+set_new_model("survival_reg")
+set_model_mode("survival_reg", "censored regression")
+
+# ------------------------------------------------------------------------------
+
+# parnip just contains the model specification, the engines are the censored package.