default engine changes for #513

Author: topepo

NEWS.md

@@ -1,5 +1,9 @@
 # parsnip (development version)
 
+* Each model now has a default engine that is used when the model is defined. The default for each model is listed in the help documents. This also adds functionality to change to declare an engine in the model specification function. `set_engine()` is still required if engine-specific arguments need to be added. (#513)
+
+* The default engine for `multinom_reg()` was changed to `nnet`. 
+
 * The helper functions `.convert_form_to_xy_fit()`, `.convert_form_to_xy_new()`, `.convert_xy_to_form_fit()`, and  `.convert_xy_to_form_new()` for converting between formula and matrix interface are now exported for developer use (#508).
 
 * Fix bug in `augment()` when non-predictor, non-outcome variables are included in data (#510).

R/boost_tree.R

@@ -32,6 +32,8 @@
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"xgboost"`.
 #' @param mtry A number for the number (or proportion) of predictors that will
 #'  be randomly sampled at each split when creating the tree models (`xgboost`
 #'  only).
@@ -92,6 +94,7 @@
 
 boost_tree <-
   function(mode = "unknown",
+           engine = "xgboost",
            mtry = NULL, trees = NULL, min_n = NULL,
            tree_depth = NULL, learn_rate = NULL,
            loss_reduction = NULL,
@@ -114,7 +117,7 @@ boost_tree <-
       eng_args = NULL,
       mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/decision_tree.R

@@ -24,6 +24,8 @@
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"rpart"`.
 #' @param cost_complexity A positive number for the the cost/complexity
 #'   parameter (a.k.a. `Cp`) used by CART models (`rpart` only).
 #' @param tree_depth An integer for maximum depth of the tree.
@@ -69,7 +71,8 @@
 #' @export
 
 decision_tree <-
-  function(mode = "unknown", cost_complexity = NULL, tree_depth = NULL, min_n = NULL) {
+  function(mode = "unknown", engine = "rpart", cost_complexity = NULL,
+           tree_depth = NULL, min_n = NULL) {
 
     args <- list(
       cost_complexity   = enquo(cost_complexity),
@@ -83,7 +86,7 @@ decision_tree <-
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/linear_reg.R

@@ -18,6 +18,8 @@
 #'  in lieu of recreating the object from scratch.
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "regression".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"lm"`.
 #' @param penalty A non-negative number representing the total
 #'  amount of regularization (`glmnet`, `keras`, and `spark` only).
 #'  For `keras` models, this corresponds to purely L2 regularization
@@ -70,6 +72,7 @@
 #' @importFrom purrr map_lgl
 linear_reg <-
   function(mode = "regression",
+           engine = "lm",
            penalty = NULL,
            mixture = NULL) {
 
@@ -84,7 +87,7 @@ linear_reg <-
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/logistic_reg.R

@@ -18,6 +18,8 @@
 #'  in lieu of recreating the object from scratch.
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "classification".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"glm"`.
 #' @param penalty A non-negative number representing the total
 #'  amount of regularization (`glmnet`, `LiblineaR`, `keras`, and `spark` only).
 #'  For `keras` models, this corresponds to purely L2 regularization
@@ -69,6 +71,7 @@
 #' @importFrom purrr map_lgl
 logistic_reg <-
   function(mode = "classification",
+           engine = "glm",
            penalty = NULL,
            mixture = NULL) {
 
@@ -83,7 +86,7 @@ logistic_reg <-
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/mars.R

@@ -25,6 +25,8 @@
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"earth"`.
 #' @param num_terms The number of features that will be retained in the
 #'    final model, including the intercept.
 #' @param prod_degree The highest possible interaction degree.
@@ -45,7 +47,7 @@
 #' mars(mode = "regression", num_terms = 5)
 #' @export
 mars <-
-  function(mode = "unknown",
+  function(mode = "unknown", engine = "earth",
            num_terms = NULL, prod_degree = NULL, prune_method = NULL) {
 
     args <- list(
@@ -60,7 +62,7 @@ mars <-
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/mlp.R

@@ -30,6 +30,8 @@
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", "regression", or
 #'  "classification".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"nnet"`.
 #' @param hidden_units An integer for the number of units in the hidden model.
 #' @param penalty A non-negative numeric value for the amount of weight
 #'  decay.
@@ -63,7 +65,7 @@
 #' @export
 
 mlp <-
-  function(mode = "unknown",
+  function(mode = "unknown", engine = "nnet",
            hidden_units = NULL, penalty = NULL, dropout = NULL, epochs = NULL,
            activation = NULL) {
 
@@ -81,7 +83,7 @@ mlp <-
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/multinom_reg.R

@@ -18,6 +18,8 @@
 #'  in lieu of recreating the object from scratch.
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "classification".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"nnet"`.
 #' @param penalty A non-negative number representing the total
 #'  amount of regularization (`glmnet`, `keras`, and `spark` only).
 #'  For `keras` models, this corresponds to purely L2 regularization
@@ -33,7 +35,7 @@
 #' The model can be created using the `fit()` function using the
 #'  following _engines_:
 #' \itemize{
-#' \item \pkg{R}:   `"glmnet"`  (the default), `"nnet"`
+#' \item \pkg{R}:   `"glmnet"`, `"nnet"` (the default)
 #' \item \pkg{Spark}: `"spark"`
 #' \item \pkg{keras}: `"keras"`
 #' }
@@ -64,6 +66,7 @@
 #' @importFrom purrr map_lgl
 multinom_reg <-
   function(mode = "classification",
+           engine = "nnet",
            penalty = NULL,
            mixture = NULL) {
 
@@ -78,7 +81,7 @@ multinom_reg <-
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }
 

R/nearest_neighbor.R

@@ -26,7 +26,8 @@
 #' @param mode A single character string for the type of model.
 #' Possible values for this model are `"unknown"`, `"regression"`, or
 #' `"classification"`.
-#'
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"kknn"`.
 #' @param neighbors A single integer for the number of neighbors
 #' to consider (often called `k`). For \pkg{kknn}, a value of 5
 #' is used if `neighbors` is not specified.
@@ -57,6 +58,7 @@
 #'
 #' @export
 nearest_neighbor <- function(mode = "unknown",
+                             engine = "kknn",
                              neighbors = NULL,
                              weight_func = NULL,
                              dist_power = NULL) {
@@ -72,7 +74,7 @@ nearest_neighbor <- function(mode = "unknown",
     eng_args = NULL,
     mode = mode,
     method = NULL,
-    engine = NULL
+    engine = engine
   )
 }
 

R/proportional_hazards.R

@@ -18,6 +18,8 @@
 #'
 #' @param mode A single character string for the type of model.
 #'  Possible values for this model are "unknown", or "censored regression".
+#' @param engine A character string for the method of fitting. Possible engines
+#' are listed above. The default for this model is `"survival"`.
 #' @inheritParams linear_reg
 #'
 #' @details
@@ -29,9 +31,11 @@
 #' show_engines("proportional_hazards")
 #' @keywords internal
 #' @export
-proportional_hazards <- function(mode = "censored regression",
-                    penalty = NULL,
-                    mixture = NULL) {
+proportional_hazards <- function(
+  mode = "censored regression",
+  engine = "survival",
+  penalty = NULL,
+  mixture = NULL) {
 
     args <- list(
       penalty = enquo(penalty),
@@ -44,7 +48,7 @@ proportional_hazards <- function(mode = "censored regression",
       eng_args = NULL,
       mode = mode,
       method = NULL,
-      engine = NULL
+      engine = engine
     )
   }