Name translations (#735)

* function for translating names

* update argument name

* some unit tests

* global var false positive

* add missing pkgdown entry

* Fix typos and refine docs

* Less confusing wording

Co-authored-by: Julia Silge <julia.silge@gmail.com>

Author: topepo

NAMESPACE

@@ -156,6 +156,7 @@ export(.convert_xy_to_form_new)
 export(.dat)
 export(.facts)
 export(.lvls)
+export(.model_param_name_key)
 export(.obs)
 export(.organize_glmnet_pred)
 export(.preds)

NEWS.md

@@ -19,6 +19,8 @@
 
 * `predict(type = "prob")` will now provide an error if the outcome variable has a level called `"class"` (#720).
 
+* Added a developer function, `.model_param_name_key` that translates names of tuning parameters.
+
 * Model type functions will now message informatively if a needed parsnip extension package is not loaded (#731).
 
 

R/parsnip-package.R

@@ -41,7 +41,7 @@ utils::globalVariables(
     "sub_neighbors", ".pred_class", "x", "y", "predictor_indicators",
     "compute_intercept", "remove_intercept", "estimate", "term",
     "call_info", "component", "component_id", "func", "tunable", "label",
-    "pkg", ".order", "item", "tunable", "has_ext", "weights", "has_wts", "protect"
+    "pkg", ".order", "item", "tunable", "has_ext", "id", "weights", "has_wts", "protect"
   )
 )
 

R/translate.R

@@ -179,3 +179,62 @@ add_methods <- function(x, engine) {
   x$method <- get_model_spec(specific_model(x), x$mode, x$engine)
   x
 }
+
+
+#' Translate names of model tuning parameters
+#'
+#' This function creates a key that connects the identifiers users make for
+#' tuning parameter names, the standardized parsnip parameter names, and the
+#' argument names to the underlying fit function for the engine.
+#'
+#' @param object A workflow or parsnip model specification.
+#' @param as_tibble A logical. Should the results be in a tibble (the default)
+#' or in a list that can facilitate renaming grid objects?
+#' @return A tibble with columns `user`, `parsnip`, and `engine`, or a list
+#' with named character vectors `user_to_parsnip` and `parsnip_to_engine`.
+#' @examples
+#' mod <-
+#'  linear_reg(penalty = tune("regularization"), mixture = tune()) %>%
+#'  set_engine("glmnet")
+#'
+#' mod %>% .model_param_name_key()
+#'
+#' rn <- mod %>% .model_param_name_key(as_tibble = FALSE)
+#' rn
+#'
+#' grid <- tidyr::crossing(regularization = c(0, 1), mixture = (0:3) / 3)
+#'
+#' grid %>%
+#'   dplyr::rename(!!!rn$user_to_parsnip)
+#'
+#' grid %>%
+#'   dplyr::rename(!!!rn$user_to_parsnip) %>%
+#'   dplyr::rename(!!!rn$parsnip_to_engine)
+#' @export
+.model_param_name_key <- function(object, as_tibble = TRUE) {
+  if (!inherits(object, c("model_spec", "workflow"))) {
+    rlang::abort("'object' should be a model specification or workflow.")
+  }
+  if (inherits(object, "workflow")) {
+    object <- hardhat::extract_spec_parsnip(object)
+  }
+
+  # To translate from given names/ids in grid to parsnip names:
+  params <- object %>% hardhat::extract_parameter_set_dials()
+  params <- tibble::as_tibble(params) %>%
+    dplyr::select(user = id, parsnip = name)
+  # Go from parsnip names to engine names
+  arg_key <- get_from_env(paste0(class(object)[1], "_args")) %>%
+    dplyr::filter(engine == object$engine) %>%
+    dplyr::select(engine = original, parsnip)
+
+  res <- dplyr::left_join(params, arg_key, by = "parsnip")
+  if (!as_tibble) {
+    res0 <- list(user_to_parsnip = res$user, parsnip_to_engine = res$parsnip)
+    names(res0$user_to_parsnip) <- res$parsnip
+    names(res0$parsnip_to_engine) <- res$engine
+    res <- res0
+  }
+  res
+}
+

_pkgdown.yml

@@ -101,3 +101,4 @@ reference:
       - required_pkgs
       - required_pkgs.model_spec
       - req_pkgs
+      - .model_param_name_key

man/dot-model_param_name_key.Rd

@@ -17,6 +17,5 @@ StripTrailingWhitespace: Yes
 
 BuildType: Package
 PackageUseDevtools: Yes
-PackageCleanBeforeInstall: Yes
 PackageInstallArgs: --no-multiarch --with-keep.source
 PackageRoxygenize: rd,collate,namespace

parsnip.Rproj

@@ -269,3 +269,17 @@ test_that("arguments (svm_rbf)", {
   expect_snapshot(translate_args(rbf_sigma %>% set_engine("kernlab")))
 })
 
+# ------------------------------------------------------------------------------
+
+test_that("translate tuning paramter names", {
+
+  mod <- boost_tree(trees = tune("number of trees"), min_n = tune(), tree_depth = 3)
+
+  expect_snapshot(.model_param_name_key(mod))
+  expect_snapshot(.model_param_name_key(mod, as_tibble = FALSE))
+  expect_snapshot(.model_param_name_key(linear_reg()))
+  expect_snapshot(.model_param_name_key(linear_reg(), as_tibble = FALSE))
+  expect_snapshot_error(.model_param_name_key(1))
+})
+
+