Revised model documentation

DESCRIPTION

@@ -53,4 +53,5 @@ Suggests:
     nlme,
     modeldata,
     LiblineaR,
-    Matrix
+    Matrix,
+    dials

NAMESPACE

@@ -122,6 +122,7 @@ export(control_parsnip)
 export(convert_stan_interval)
 export(decision_tree)
 export(eval_args)
+export(find_engine_files)
 export(fit)
 export(fit.model_spec)
 export(fit_control)

R/aaa_models.R

@@ -911,3 +911,64 @@ get_encoding <- function(model) {
   }
   res
 }
+
+#' Tools for documenting packages
+#' @param mod A character string for the model file
+#' @param pkg The package that contains the model file
+#' @return `find_engine_files()` returns a character string.
+#' @name doc-tools
+#' @keywords internal
+#' @export
+#' @examples
+#' cat(find_engine_files("linear_reg"))
+find_engine_files <- function(mod) {
+
+  # Get available topics
+  topic_names <- search_for_engine_docs(mod)
+  if (length(topic_names) == 0) {
+    return(character(0))
+  }
+
+  # Subset for our model function
+  eng <- strsplit(topic_names, "-")
+  eng <- purrr::map_chr(eng, ~ .x[length(.x)])
+  eng <- tibble::tibble(engine = eng, topic = topic_names)
+
+  # Combine them to keep the order in which they were registered
+  all_eng <- get_from_env(mod)
+  all_eng$.order <- 1:nrow(all_eng)
+  eng <- dplyr::left_join(eng, all_eng, by = "engine")
+  eng <- eng[order(eng$.order),]
+
+  res <-
+    glue::glue("  \\item \\code{\\link[=|eng$topic|]{|eng$engine|}} ",
+               .open = "|", .close = "|")
+
+  res <- paste0("\\itemize{\n", paste0(res, collapse = "\n"), "\n}")
+  res
+}
+
+search_for_engine_docs <- function(mod) {
+  all_deps <- get_from_env(paste0(mod, "_pkgs"))
+  all_deps <- unlist(all_deps$pkg)
+  all_deps <- unique(c("parsnip", all_deps))
+  excl <- c("stats", "magrittr")
+  all_deps <- all_deps[!(all_deps %in% excl)]
+  res <- purrr::map(all_deps, parsnip:::find_details_topics, mod = mod)
+  res <- unique(unlist(res))
+  res
+}
+
+find_details_topics <- function(pkg, mod) {
+  mod <- gsub("_", "-", mod)
+  meta_loc <- system.file("Meta/Rd.rds", package = pkg)
+  meta_loc <- meta_loc[meta_loc != ""]
+  if (length(meta_loc) > 0) {
+    topic_names <- readRDS(meta_loc)$Name
+    res <- grep(paste0("details-", mod), topic_names, value = TRUE)
+  } else {
+    res <- character(0)
+  }
+  res
+}
+

R/linear-reg-doc-glmnet.R

@@ -0,0 +1,9 @@
+#' Linear regression via glmnet
+#'
+#' `glmnet()` uses regularized least squares to fit models with numeric outcomes.
+#'
+#' @includeRmd man/rmd/linear-reg-glmnet.Rmd details
+#'
+#' @name details-linear-reg-glmnet
+#' @keywords internal
+NULL

R/linear-reg-doc-keras.R

@@ -0,0 +1,9 @@
+#' Linear regression via keras/tensorflow
+#'
+#' This model uses regularized least squares to fit models with numeric outcomes.
+#'
+#' @includeRmd man/rmd/linear-reg-keras.Rmd details
+#'
+#' @name details-linear-reg-keras
+#' @keywords internal
+NULL

R/linear-reg-doc-lm.R

@@ -0,0 +1,9 @@
+#' Linear regression via lm
+#'
+#' [stats::lm()] uses ordinary least squares to fit models with numeric outcomes.
+#'
+#' @includeRmd man/rmd/linear-reg-lm.Rmd details
+#'
+#' @name details-linear-reg-lm
+#' @keywords internal
+NULL

R/linear-reg-doc-spark.R

@@ -0,0 +1,10 @@
+#' Linear regression via spark
+#'
+#' `sparklyr::ml_linear_regression()` uses regularized least squares to fit
+#' models with numeric outcomes.
+#'
+#' @includeRmd man/rmd/linear-reg-spark.Rmd details
+#'
+#' @name details-linear-reg-spark
+#' @keywords internal
+NULL

R/linear-reg-doc-stan.R

@@ -0,0 +1,9 @@
+#' Linear regression via Bayesian Methods
+#'
+#' The `stan` engine estimates regression parameters using Bayesian estimation.
+#'
+#' @includeRmd man/rmd/linear-reg-stan.Rmd details
+#'
+#' @name details-linear-reg-stan
+#' @keywords internal
+NULL

R/linear_reg.R

@@ -1,72 +1,36 @@
 #' General Interface for Linear Regression Models
 #'
-#' `linear_reg()` is a way to generate a _specification_ of a model
-#'  before fitting and allows the model to be created using
-#'  different packages in R, Stan, keras, or via Spark. The main
-#'  arguments for the model are:
-#' \itemize{
-#'   \item \code{penalty}: The total amount of regularization
-#'  in the model. Note that this must be zero for some engines.
-#'   \item \code{mixture}: The mixture amounts of different types of
-#'   regularization (see below). Note that this will be ignored for some engines.
-#' }
-#' These arguments are converted to their specific names at the
-#'  time that the model is fit. Other options and arguments can be
-#'  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.
+#' @description
+#'
+#' `linear_reg()` defines a model that can predict numeric values from
+#' predictors using a linear function.
+#'
+#' There are different ways to fit this model. Information about the available
+#' _engines_ that that can be used for fitting:
+#'
+#' \Sexpr[stage=render,results=rd]{parsnip:::find_engine_files("linear_reg")}
+#'
 #' @inheritParams boost_tree
 #' @param mode A single character string for the type of model.
 #'  The only possible value for this model is "regression".
 #' @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
-#'  (aka weight decay) while the other models can be a combination
-#'  of L1 and L2 (depending on the value of `mixture`; see below).
+#'  amount of regularization (specific engines only).
 #' @param mixture A number between zero and one (inclusive) that is the
 #'  proportion of L1 regularization (i.e. lasso) in the model. When
 #'  `mixture = 1`, it is a pure lasso model while `mixture = 0` indicates that
-#'  ridge regression is being used. (`glmnet` and `spark` only).
+#'  ridge regression is being used  (specific engines 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
-#'  mode will always be "regression".
-#'
-#' The model can be created using the `fit()` function using the
-#'  following _engines_:
-#' \itemize{
-#' \item \pkg{R}:  `"lm"`  (the default) or `"glmnet"`
-#' \item \pkg{Stan}:  `"stan"`
-#' \item \pkg{Spark}: `"spark"`
-#' \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
+#' This function only defines what _type_ of model is being fit. Once an engine
+#'  is specified, the _method_ to fit the model is also defined.
 #'
-#' @note For models created using the spark engine, there are
-#'  several differences to consider. First, only the formula
-#'  interface to via `fit()` is available; using `fit_xy()` will
-#'  generate an error. Second, the predictions will always be in a
-#'  spark table format. The names will be the same as documented but
-#'  without the dots. Third, there is no equivalent to factor
-#'  columns in spark tables so class predictions are returned as
-#'  character columns. Fourth, to retain the model object for a new
-#'  R session (via `save()`), the `model$fit` element of the `parsnip`
-#'  object should be serialized via `ml_save(object$fit)` and
-#'  separately saved to disk. In a new session, the object can be
-#'  reloaded and reattached to the `parsnip` object.
+#' The model is not trained or fit until the [fit.model_spec()] function is used
+#' with the data.
 #'
 #' @seealso [fit()], [set_engine()]
 #' @examples
 #' show_engines("linear_reg")
 #'
 #' linear_reg()
-#' # Parameters can be represented by a placeholder:
-#' linear_reg(penalty = varying())
 #' @export
 #' @importFrom purrr map_lgl
 linear_reg <-