Merge pull request #366 from tidymodels/engine-docs

Engine docs for #362

Author: topepo

.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())