Engine docs for #362

.github/workflows/R-CMD-check.yaml

@@ -1,7 +1,10 @@
 on:
   push:
+    branches:
+      - master
   pull_request:
-    types: [opened, synchronize, reopened]
+    branches:
+      - master
 
 name: R-CMD-check
 
@@ -18,7 +21,7 @@ jobs:
           - {os: macOS-latest,   r: 'release'}
           - {os: windows-latest, r: 'release'}
           - {os: windows-latest, r: '3.6'}
-          - {os: ubuntu-16.04,   r: 'devel', rspm: "https://packagemanager.rstudio.com/cran/__linux__/xenial/latest"}
+          - {os: ubuntu-16.04,   r: 'devel', rspm: "https://packagemanager.rstudio.com/cran/__linux__/xenial/latest", http-user-agent: "R/4.0.0 (ubuntu-16.04) R (4.0.0 x86_64-pc-linux-gnu x86_64 linux-gnu) on GitHub Actions" }
           - {os: ubuntu-16.04,   r: 'release', rspm: "https://packagemanager.rstudio.com/cran/__linux__/xenial/latest"}
           - {os: ubuntu-16.04,   r: 'oldrel',  rspm: "https://packagemanager.rstudio.com/cran/__linux__/xenial/latest"}
           - {os: ubuntu-16.04,   r: '3.5',     rspm: "https://packagemanager.rstudio.com/cran/__linux__/xenial/latest"}
@@ -34,6 +37,7 @@ jobs:
       - uses: r-lib/actions/setup-r@master
         with:
           r-version: ${{ matrix.config.r }}
+          http-user-agent: ${{ matrix.config.http-user-agent }}
 
       - uses: r-lib/actions/setup-pandoc@master
 
@@ -79,7 +83,7 @@ jobs:
         run: |
           reticulate::conda_create('r-reticulate', packages = c('python==3.6.9'))
           tensorflow::install_tensorflow(version='1.14.0')
-        shell: Rscript {0}
+        shell: Rscript {0}        
 
       - name: Session info
         run: |

NAMESPACE

@@ -168,6 +168,7 @@ export(set_model_mode)
 export(set_new_model)
 export(set_pred)
 export(show_call)
+export(show_engines)
 export(show_fit)
 export(show_model_info)
 export(surv_reg)

NEWS.md

@@ -1,5 +1,7 @@
 # parsnip (development version)
 
+* `show_engines()` will provide information on the current set for a model. 
+
 # parsnip 0.1.3
 
  * A `glance()` method for `model_fit` objects was added (#325)

R/boost_tree.R

@@ -62,6 +62,8 @@
 #' \item \pkg{Spark}: `"spark"`
 #' }
 #'
+#' For this model, other packages may add additional engines. Use
+#' [show_engines()] to see the current set of engines.
 #'
 #' @includeRmd man/rmd/boost-tree.Rmd details
 #'
@@ -81,6 +83,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()], [set_engine()]
 #' @examples
+#' show_engines("boost_tree")
+#'
 #' boost_tree(mode = "classification", trees = 20)
 #' # Parameters can be represented by a placeholder:
 #' boost_tree(mode = "regression", mtry = varying())

R/decision_tree.R

@@ -62,6 +62,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()]
 #' @examples
+#' show_engines("decision_tree")
+#'
 #' decision_tree(mode = "classification", tree_depth = 5)
 #' # Parameters can be represented by a placeholder:
 #' decision_tree(mode = "regression", cost_complexity = varying())

R/engines.R

@@ -106,3 +106,24 @@ set_engine <- function(object, engine, ...) {
     engine = object$engine
   )
 }
+
+#' Display available engines for a model
+#'
+#' The possible engines for a model may depend on what packages are loaded. There
+#' are some `parsnip`-adjacent packages that only add engines to existing models.
+#' @param x The name of a `parsnip` model (e.g., "linear_reg", "mars", etc.)
+#' @return A tibble.
+#' show_engines("linear_reg")
+#' @export
+show_engines <- function(x) {
+  if (!is.character(x) || length(x) > 1) {
+    rlang::abort("`show_engines()` takes a single character string as input.")
+  }
+  res <- try(get_from_env(x), silent = TRUE)
+  if (inherits(res, "try-error")) {
+    rlang::abort(
+      paste0("No results found for model function '", x, "'.")
+    )
+  }
+  res
+}

R/linear_reg.R

@@ -42,6 +42,9 @@
 #' \item \pkg{keras}: `"keras"`
 #' }
 #'
+#' For this model, other packages may add additional engines. Use
+#' [show_engines()] to see the current set of engines.
+#'
 #' @includeRmd man/rmd/linear-reg.Rmd details
 #'
 #' @note For models created using the spark engine, there are
@@ -59,6 +62,8 @@
 #'
 #' @seealso [fit()], [set_engine()]
 #' @examples
+#' show_engines("linear_reg")
+#'
 #' linear_reg()
 #' # Parameters can be represented by a placeholder:
 #' linear_reg(penalty = varying())

R/logistic_reg.R

@@ -40,6 +40,9 @@
 #' \item \pkg{keras}: `"keras"`
 #' }
 #'
+#' For this model, other packages may add additional engines. Use
+#' [show_engines()] to see the current set of engines.
+#'
 #' @includeRmd man/rmd/logistic-reg.Rmd details
 #'
 #' @note For models created using the spark engine, there are
@@ -57,6 +60,8 @@
 #'
 #' @seealso [fit()]
 #' @examples
+#' show_engines("logistic_reg")
+#'
 #' logistic_reg()
 #' # Parameters can be represented by a placeholder:
 #' logistic_reg(penalty = varying())

R/mars.R

@@ -41,6 +41,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()]
 #' @examples
+#' show_engines("mars")
+#'
 #' mars(mode = "regression", num_terms = 5)
 #' @export
 mars <-

R/mlp.R

@@ -56,6 +56,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()]
 #' @examples
+#' show_engines("mlp")
+#'
 #' mlp(mode = "classification", penalty = 0.01)
 #' # Parameters can be represented by a placeholder:
 #' mlp(mode = "regression", hidden_units = varying())

R/multinom_reg.R

@@ -56,6 +56,8 @@
 #'
 #' @seealso [fit()]
 #' @examples
+#' show_engines("multinom_reg")
+#'
 #' multinom_reg()
 #' # Parameters can be represented by a placeholder:
 #' multinom_reg(penalty = varying())

R/nearest_neighbor.R

@@ -51,6 +51,8 @@
 #' @seealso [fit()]
 #'
 #' @examples
+#' show_engines("nearest_neighbor")
+#'
 #' nearest_neighbor(neighbors = 11)
 #'
 #' @export

R/rand_forest.R

@@ -56,6 +56,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()]
 #' @examples
+#' show_engines("rand_forest")
+#'
 #' rand_forest(mode = "classification", trees = 2000)
 #' # Parameters can be represented by a placeholder:
 #' rand_forest(mode = "regression", mtry = varying())

R/surv_reg.R

@@ -45,6 +45,8 @@
 #' @references Jackson, C. (2016). `flexsurv`: A Platform for Parametric Survival
 #'  Modeling in R. _Journal of Statistical Software_, 70(8), 1 - 33.
 #' @examples
+#' show_engines("surv_reg")
+#'
 #' surv_reg()
 #' # Parameters can be represented by a placeholder:
 #' surv_reg(dist = varying())

R/svm_poly.R

@@ -41,6 +41,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()]
 #' @examples
+#' show_engines("svm_poly")
+#'
 #' svm_poly(mode = "classification", degree = 1.2)
 #' # Parameters can be represented by a placeholder:
 #' svm_poly(mode = "regression", cost = varying())

R/svm_rbf.R

@@ -42,6 +42,8 @@
 #' @importFrom purrr map_lgl
 #' @seealso [fit()]
 #' @examples
+#' show_engines("svm_rbf")
+#'
 #' svm_rbf(mode = "classification", rbf_sigma = 0.2)
 #' # Parameters can be represented by a placeholder:
 #' svm_rbf(mode = "regression", cost = varying())

man/rmd/boost-tree.Rmd

@@ -38,6 +38,9 @@ mod_param <-
   update(sample_size = sample_prop(c(0.4, 0.9)))
 ```
 
+For this engine, tuning over `trees` is very efficient since the same model 
+object can be used to make predictions over multiple values of `trees`.  
+
 Finally, note that `xgboost` models require that non-numeric predictors (e.g., factors) must be converted to dummy variables or some other numeric representation. By default, when using `fit()` with `xgboost`, a one-hot encoding is used to convert factor predictors to indicator variables. 
 
 
@@ -52,6 +55,9 @@ boost_tree() %>%
 
 Note that [C50::C5.0()] does not require factor predictors to be converted  to indicator variables. `fit()` does not affect the encoding of the predictor values (i.e. factors stay factors) for this model.
 
+For this engine, tuning over `trees` is very efficient since the same model 
+object can be used to make predictions over multiple values of `trees`.  
+
 ## spark
 
 ```{r spark-reg}

man/rmd/mars.Rmd

@@ -26,6 +26,8 @@ Note that, when the model is fit, the `earth` package only has its  namespace lo
 
 Also, `fit()` passes the data directly to `earth::earth()` so that its formula method can create dummy variables as-needed. 
 
+For this engine, tuning over `num_terms` is very efficient since the same model 
+object can be used to make predictions over multiple values of `num_terms`.  
 
 ## Parameter translations