add argument interval for survival/quantile predictions (#615)

* add `level` to `predict_survival()`

* add `interval` arg for prediction

* only inherit parameter docs, not all docs

* add `level` to `predict_quantile()`

Author: hfrick

NEWS.md

@@ -14,9 +14,11 @@
 
 ## Other Changes
 
- * When the xy interface is used and the underlying model expects to use a matrix, a better warning is issued when predictors contain non-numeric columns (including dates). 
+* When the xy interface is used and the underlying model expects to use a matrix, a better warning is issued when predictors contain non-numeric columns (including dates). 
 
- * The fit time is only calculated when the `verbosity` argument of `control_parsnip()` is 2L or greater. Also, the call to `system.time()` now uses `gcFirst = FALSE`. (#611)
+* The fit time is only calculated when the `verbosity` argument of `control_parsnip()` is 2L or greater. Also, the call to `system.time()` now uses `gcFirst = FALSE`. (#611)
+ 
+* Argument `interval` was added for prediction: For types "survival" and "quantile", estimates for the confidence or prediction interval can be added if available (#615).
 
 # parsnip 0.1.7
 

R/bart.R

@@ -162,10 +162,11 @@ update.bart <-
   }
 
 
+#' Developer functions for predictions via BART models
 #' @export
 #' @keywords internal
 #' @name bart-internal
-#' @inherit predict.model_fit
+#' @inheritParams predict.model_fit
 #' @param obj A parsnip object.
 #' @param ci Confidence (TRUE) or prediction interval (FALSE)
 #' @param level Confidence level.

R/predict.R

@@ -19,8 +19,11 @@
 #'  `parsnip` related options that can be passed, depending on the
 #'  value of `type`. Possible arguments are:
 #'  \itemize{
-#'     \item `level`: for `type`s of "conf_int" and "pred_int" this
-#'            is the parameter for the tail area of the intervals
+#'     \item `interval`: for `type`s of "survival" and "quantile", should
+#'            interval estimates be added, if available? Options are `"none"`
+#'            and `"confidence"`.
+#'     \item `level`: for `type`s of "conf_int", "pred_int", and "survival"
+#'            this is the parameter for the tail area of the intervals
 #'            (e.g. confidence level for confidence intervals).
 #'            Default value is 0.95.
 #'     \item `std_error`: add the standard error of fit or prediction (on
@@ -82,12 +85,10 @@
 #' For censored regression:
 #'
 #'  * `type = "time"` produces a column `.pred_time`.
-#'  * `type = "hazard"` results in a column `.pred_hazard`.
-#'  * `type = "survival"` results in a list column containing tibbles with a
-#'     `.pred_survival` column.
-#'
-#'  For the last two types, the results are a nested tibble with an overall
-#'  column called `.pred` with sub-tibbles with the above format.
+#'  * `type = "hazard"` results in a list column `.pred` containing tibbles
+#'     with a column `.pred_hazard`.
+#'  * `type = "survival"` results in a list column `.pred` containing tibbles
+#'     with a `.pred_survival` column.
 #'
 #' In the case of Spark-based models, since table columns cannot
 #'  contain dots, the same convention is used except 1) no dots
@@ -98,6 +99,7 @@
 #'  `predict()` function will return the same structure as above but
 #'  filled with missing values. This does not currently work for
 #'  multivariate models.
+#'
 #' @examples
 #' library(dplyr)
 #'
@@ -309,7 +311,7 @@ check_pred_type_dots <- function(object, type, ...) {
 
   # ----------------------------------------------------------------------------
 
-  other_args <- c("level", "std_error", "quantile", "time", "increasing")
+  other_args <- c("interval", "level", "std_error", "quantile", "time", "increasing")
   is_pred_arg <- names(the_dots) %in% other_args
   if (any(!is_pred_arg)) {
     bad_args <- names(the_dots)[!is_pred_arg]

R/predict_quantile.R

@@ -1,13 +1,17 @@
 #' @keywords internal
 #' @rdname other_predict
-#' @param quant A vector of numbers between 0 and 1 for the quantile being
+#' @param quantile A vector of numbers between 0 and 1 for the quantile being
 #'  predicted.
 #' @inheritParams predict.model_fit
 #' @method predict_quantile model_fit
 #' @export predict_quantile.model_fit
 #' @export
-predict_quantile.model_fit <-
-  function(object, new_data, quantile = (1:9)/10, ...) {
+predict_quantile.model_fit <- function(object,
+                                       new_data,
+                                       quantile = (1:9)/10,
+                                       interval = "none",
+                                       level = 0.95,
+                                       ...) {
 
     check_spec_pred_type(object, "quantile")
 

R/predict_survival.R

@@ -5,7 +5,7 @@
 #' @export predict_survival.model_fit
 #' @export
 predict_survival.model_fit <-
-  function(object, new_data, time, ...) {
+  function(object, new_data, time, interval = "none", level = 0.95, ...) {
 
     check_spec_pred_type(object, "survival")