function and documentation changes for set_engine

Author: topepo

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: parsnip
-Version: 0.0.0.9004
-Title: A Common API to Modeling and analysis Functions
+Version: 0.0.0.9005
+Title: A Common API to Modeling and Analysis Functions
 Description: A common interface is provided to allow users to specify a model without having to remember the different argument names across different functions or computational engines (e.g. R, spark, stan, etc). 
 Authors@R: c(
     person("Max", "Kuhn", , "max@rstudio.com", c("aut", "cre")),

NAMESPACE

@@ -102,6 +102,7 @@ export(predict_raw)
 export(predict_raw.model_fit)
 export(rand_forest)
 export(set_args)
+export(set_engine)
 export(set_mode)
 export(show_call)
 export(surv_reg)

R/boost_tree.R

@@ -22,7 +22,7 @@
 #' }
 #' These arguments are converted to their specific names at the
 #'  time that the model is fit. Other options and argument can be
-#'  set using the  `...` slot. If left to their defaults
+#'  set using the  `set_engine` function. If left to their defaults
 #'  here (`NULL`), the values are taken from the underlying model
 #'  functions.  If parameters need to be modified, `update` can be used
 #'  in lieu of recreating the object from scratch.
@@ -46,11 +46,6 @@
 #' @param sample_size An number for the number (or proportion) of data that is
 #'  exposed to the fitting routine. For `xgboost`, the sampling is done at at
 #'  each iteration while `C5.0` samples once during traning.
-#' @param ... Other arguments to pass to the specific engine's
-#'  model fit function (see the Engine Details section below). This
-#'  should not include arguments defined by the main parameters to
-#'  this function. For the `update` function, the ellipses can
-#'  contain the primary arguments or any others.
 #' @details
 #' The data given to the function are not saved and are only used
 #'  to determine the _mode_ of the model. For `boost_tree`, the
@@ -63,17 +58,12 @@
 #' \item \pkg{Spark}: `"spark"`
 #' }
 #'
-#' Main parameter arguments (and those in `...`) can avoid
-#'  evaluation until the underlying function is executed by wrapping the
-#'  argument in [rlang::expr()] (e.g. `mtry = expr(floor(sqrt(p)))`).
-#'
 #'
 #' @section Engine Details:
 #'
 #' Engines may have pre-set default arguments when executing the
-#'  model fit call. These can be changed by using the `...`
-#'  argument to pass in the preferred values. For this type of
-#'  model, the template of the fit calls are:
+#'  model fit call.  For this type of model, the template of the
+#'  fit calls are:
 #'
 #' \pkg{xgboost} classification
 #'
@@ -109,7 +99,7 @@
 #'  reloaded and reattached to the `parsnip` object.
 #'
 #' @importFrom purrr map_lgl
-#' @seealso [varying()], [fit()]
+#' @seealso [varying()], [fit()], [set_engine()]
 #' @examples
 #' boost_tree(mode = "classification", trees = 20)
 #' # Parameters can be represented by a placeholder:
@@ -121,11 +111,7 @@ boost_tree <-
            mtry = NULL, trees = NULL, min_n = NULL,
            tree_depth = NULL, learn_rate = NULL,
            loss_reduction = NULL,
-           sample_size = NULL,
-           ...) {
-
-    others <- enquos(...)
-
+           sample_size = NULL) {
     args <- list(
       mtry = enquo(mtry),
       trees = enquo(trees),
@@ -141,10 +127,7 @@ boost_tree <-
            paste0("'", boost_tree_modes, "'", collapse = ", "),
            call. = FALSE)
 
-    no_value <- !vapply(others, null_value, logical(1))
-    others <- others[no_value]
-
-    out <- list(args = args, others = others,
+    out <- list(args = args, others = NULL,
                 mode = mode, method = NULL, engine = NULL)
     class(out) <- make_classes("boost_tree")
     out
@@ -183,11 +166,7 @@ update.boost_tree <-
            mtry = NULL, trees = NULL, min_n = NULL,
            tree_depth = NULL, learn_rate = NULL,
            loss_reduction = NULL, sample_size = NULL,
-           fresh = FALSE,
-           ...) {
-
-    others <- enquos(...)
-
+           fresh = FALSE) {
     args <- list(
       mtry = enquo(mtry),
       trees = enquo(trees),
@@ -209,23 +188,20 @@ update.boost_tree <-
         object$args[names(args)] <- args
     }
 
-    if (length(others) > 0) {
-      if (fresh)
-        object$others <- others
-      else
-        object$others[names(others)] <- others
-    }
-
     object
   }
 
 # ------------------------------------------------------------------------------
 
 #' @export
-translate.boost_tree <- function(x, engine, ...) {
+translate.boost_tree <- function(x, engine = x$engine, ...) {
+  if (is.null(engine)) {
+    message("Used `engine = 'xgboost'` for translation.")
+    engine <- "xgboost"
+  }
   x <- translate.default(x, engine, ...)
 
-  if (x$engine == "spark") {
+  if (engine == "spark") {
     if (x$mode == "unknown")
       stop(
         "For spark boosted trees models, the mode cannot be 'unknown' ",

R/fit.R

@@ -17,15 +17,11 @@
 #'  below). A data frame containing all relevant variables (e.g.
 #'  outcome(s), predictors, case weights, etc). Note: when needed, a
 #'  \emph{named argument} should be used.
-#' @param engine A character string for the software that should
-#'  be used to fit the model. This is highly dependent on the type
-#'  of model (e.g. linear regression, random forest, etc.).
 #' @param control A named list with elements `verbosity` and
 #'  `catch`. See [fit_control()].
 #' @param ... Not currently used; values passed here will be
 #'  ignored. Other options required to fit the model should be
-#'  passed using the `others` argument in the original model
-#'  specification.
+#'  passed using `set_engine`.
 #' @details  `fit` and `fit_xy` substitute the current arguments in the model
 #'  specification into the computational engine's code, checks them
 #'  for validity, then fits the model using the data and the
@@ -92,11 +88,13 @@ fit.model_spec <-
   function(object,
            formula = NULL,
            data = NULL,
-           engine = object$engine,
            control = fit_control(),
            ...
   ) {
     dots <- quos(...)
+    if (any(names(dots) == "engine"))
+      stop("Use `set_engine` to supply the engine.", call. = FALSE)
+
     if (all(c("x", "y") %in% names(dots)))
       stop("`fit.model_spec` is for the formula methods. Use `fit_xy` instead.",
            call. = FALSE)
@@ -109,10 +107,8 @@ fit.model_spec <-
     eval_env$formula <- formula
     fit_interface <-
       check_interface(eval_env$formula, eval_env$data, cl, object)
-    object$engine <- engine
-    object <- check_engine(object)
 
-    if (engine == "spark" && !inherits(eval_env$data, "tbl_spark"))
+    if (object$engine == "spark" && !inherits(eval_env$data, "tbl_spark"))
       stop(
         "spark objects can only be used with the formula interface to `fit` ",
         "with a spark data object.", call. = FALSE
@@ -122,7 +118,7 @@ fit.model_spec <-
     object <- get_method(object, engine = object$engine)
 
     check_installs(object)  # TODO rewrite with pkgman
-    # TODO Should probably just load the namespace
+
     load_libs(object, control$verbosity < 2)
 
     interfaces <- paste(fit_interface, object$method$fit$interface, sep = "_")
@@ -178,20 +174,20 @@ fit_xy.model_spec <-
   function(object,
            x = NULL,
            y = NULL,
-           engine = object$engine,
            control = fit_control(),
            ...
   ) {
+    dots <- quos(...)
+    if (any(names(dots) == "engine"))
+      stop("Use `set_engine` to supply the engine.", call. = FALSE)
 
     cl <- match.call(expand.dots = TRUE)
     eval_env <- rlang::env()
     eval_env$x <- x
     eval_env$y <- y
     fit_interface <- check_xy_interface(eval_env$x, eval_env$y, cl, object)
-    object$engine <- engine
-    object <- check_engine(object)
 
-    if (engine == "spark")
+    if (object$engine == "spark")
       stop(
         "spark objects can only be used with the formula interface to `fit` ",
         "with a spark data object.", call. = FALSE
@@ -201,7 +197,7 @@ fit_xy.model_spec <-
     object <- get_method(object, engine = object$engine)
 
     check_installs(object)  # TODO rewrite with pkgman
-    # TODO Should probably just load the namespace
+
     load_libs(object, control$verbosity < 2)
 
     interfaces <- paste(fit_interface, object$method$fit$interface, sep = "_")

R/linear_reg.R

@@ -12,7 +12,7 @@
 #' }
 #' These arguments are converted to their specific names at the
 #'  time that the model is fit. Other options and argument can be
-#'  set using the  `...` slot. If left to their defaults
+#'  set using `set_engine`. If left to their defaults
 #'  here (`NULL`), the values are taken from the underlying model
 #'  functions. If parameters need to be modified, `update` can be used
 #'  in lieu of recreating the object from scratch.
@@ -25,7 +25,6 @@
 #'  represents the proportion of regularization that is used for the
 #'  L2 penalty (i.e. weight decay, or ridge regression) versus L1
 #'  (the lasso) (`glmnet` and `spark` only).
-#'
 #' @details
 #' The data given to the function are not saved and are only used
 #'  to determine the _mode_ of the model. For `linear_reg`, the
@@ -42,8 +41,7 @@
 #' @section Engine Details:
 #'
 #' Engines may have pre-set default arguments when executing the
-#'  model fit call. These can be changed by using the `...`
-#'  argument to pass in the preferred values. For this type of
+#'  model fit call. For this type of
 #'  model, the template of the fit calls are:
 #'
 #' \pkg{lm}
@@ -92,7 +90,7 @@
 #'  separately saved to disk. In a new session, the object can be
 #'  reloaded and reattached to the `parsnip` object.
 #'
-#' @seealso [varying()], [fit()]
+#' @seealso [varying()], [fit()], [set_engine()]
 #' @examples
 #' linear_reg()
 #' # Parameters can be represented by a placeholder:
@@ -102,10 +100,7 @@
 linear_reg <-
   function(mode = "regression",
            penalty = NULL,
-           mixture = NULL,
-           ...) {
-
-    others  <- enquos(...)
+           mixture = NULL) {
 
     args <- list(
       penalty = enquo(penalty),
@@ -119,13 +114,10 @@ linear_reg <-
         call. = FALSE
       )
 
-    no_value <- !vapply(others, is.null, logical(1))
-    others <- others[no_value]
-
     # write a constructor function
     out <- list(
       args = args,
-      others = others,
+      others = NULL,
       mode = mode,
       method = NULL,
       engine = NULL
@@ -162,10 +154,7 @@ print.linear_reg <- function(x, ...) {
 update.linear_reg <-
   function(object,
            penalty = NULL, mixture = NULL,
-           fresh = FALSE,
-           ...) {
-
-    others  <- enquos(...)
+           fresh = FALSE) {
 
     args <- list(
       penalty = enquo(penalty),
@@ -182,13 +171,6 @@ update.linear_reg <-
         object$args[names(args)] <- args
     }
 
-    if (length(others) > 0) {
-      if (fresh)
-        object$others <- others
-      else
-        object$others[names(others)] <- others
-    }
-
     object
   }
 

R/logistic_reg.R

@@ -12,7 +12,7 @@
 #' }
 #' These arguments are converted to their specific names at the
 #'  time that the model is fit. Other options and argument can be
-#'  set using the  `...` slot. If left to their defaults
+#'  set using `set_engine`. If left to their defaults
 #'  here (`NULL`), the values are taken from the underlying model
 #'  functions. If parameters need to be modified, `update` can be used
 #'  in lieu of recreating the object from scratch.
@@ -39,8 +39,7 @@
 #' @section Engine Details:
 #'
 #' Engines may have pre-set default arguments when executing the
-#'  model fit call. These can be changed by using the `...`
-#'  argument to pass in the preferred values. For this type of
+#'  model fit call.  For this type of
 #'  model, the template of the fit calls are:
 #'
 #' \pkg{glm}
@@ -100,10 +99,7 @@
 logistic_reg <-
   function(mode = "classification",
            penalty = NULL,
-           mixture = NULL,
-           ...) {
-
-    others  <- enquos(...)
+           mixture = NULL) {
 
     args <- list(
       penalty = enquo(penalty),
@@ -117,13 +113,10 @@ logistic_reg <-
         call. = FALSE
       )
 
-    no_value <- !vapply(others, is.null, logical(1))
-    others <- others[no_value]
-
     # write a constructor function
     out <- list(
       args = args,
-      others = others,
+      others = NULL,
       mode = mode,
       method = NULL,
       engine = NULL
@@ -160,10 +153,7 @@ print.logistic_reg <- function(x, ...) {
 update.logistic_reg <-
   function(object,
            penalty = NULL, mixture = NULL,
-           fresh = FALSE,
-           ...) {
-
-    others  <- enquos(...)
+           fresh = FALSE) {
 
     args <- list(
       penalty = enquo(penalty),
@@ -180,13 +170,6 @@ update.logistic_reg <-
         object$args[names(args)] <- args
     }
 
-    if (length(others) > 0) {
-      if (fresh)
-        object$others <- others
-      else
-        object$others[names(others)] <- others
-    }
-
     object
   }