updated GAM documentation (#524)

* updated GAM documentation

* better description of the select_features parameter

* Update man/rmd/gen_additive_mod_mgcv.Rmd

Co-authored-by: Hannah Frick <hfrick@users.noreply.github.com>

* more wordsmithing

Co-authored-by: Hannah Frick <hfrick@users.noreply.github.com>

Author: topepo

R/gen_additive_mod.R

@@ -1,79 +1,40 @@
-# gen_additive_mod() - General Interface to Linear GAM Models
-# - backend: gam
-# - prediction:
-#   - mode = "regression" (default) uses
-#   - mode = "classification"
-
 #' Generalized additive models (GAMs)
 #'
+#' @description
 #' `gen_additive_mod()` defines a model that can use smoothed functions of
 #' numeric predictors in a generalized linear model.
 #'
 #' There are different ways to fit this model. See the engine-specific pages
 #' for more details
 #'
-#' More information on how `parsnip` is used for modeling is at
-#' \url{https://www.tidymodels.org}.
-#'
-#' @inheritParams boost_tree
-#' @param select_features TRUE or FALSE. If this is TRUE then can add an
-#'  extra penalty to each term so that it can be penalized to zero.
-#'  This means that the smoothing parameter estimation that is part of
-#'  fitting can completely remove terms from the model. If the corresponding
-#'  smoothing parameter is estimated as zero then the extra penalty has no effect.
-#'  Use `adjust_deg_free` to increase level of penalization.
-#' @param adjust_deg_free If `select_features = TRUE`, then acts as a multiplier for smoothness.
-#'  Increase this beyond 1 to produce smoother models.
-#'
-#'
-#' @return
-#' A `parsnip` model specification
-#'
-#' @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.
-#'
-#' The model is not trained or fit until the [fit.model_spec()] function is used
-#' with the data.
+#' \Sexpr[stage=render,results=rd]{parsnip:::make_engine_list("gen_additive_mod")}
 #'
-#' __gam__
+#' More information on how \pkg{parsnip} is used for modeling is at
+#' \url{https://www.tidymodels.org/}.
 #'
-#' This engine uses [mgcv::gam()] and has the following parameters,
-#' which can be modified through the [set_engine()] function.
-#'
-#' ``` {r echo=F}
-#' str(mgcv::gam)
-#' ```
-#'
-#' @section Fit Details:
-#'
-#' __MGCV Formula Interface__
-#'
-#' Fitting GAMs is accomplished using parameters including:
+#' @inheritParams boost_tree
+#' @param select_features `TRUE` or `FALSE.` If `TRUE`, the model has the
+#'  ability to eliminate a predictor (via penalization). Increasing
+#'  `adjust_deg_free` will increase the likelihood of removing predictors.
+#' @param adjust_deg_free If `select_features = TRUE`, then acts as a multiplier
+#'  for smoothness. Increase this beyond 1 to produce smoother models.
 #'
-#' - [mgcv::s()]: GAM spline smooths
-#' - [mgcv::te()]: GAM tensor product smooths
+#' @template spec-details
 #'
-#' These are applied in the `fit()` function:
+#' @template spec-references
 #'
-#' ``` r
-#' fit(value ~ s(date_mon, k = 12) + s(date_num), data = df)
-#' ```
+#' @seealso \Sexpr[stage=render,results=rd]{parsnip:::make_seealso_list("gen_additive_mod")}
 #'
-#' @references \url{https://www.tidymodels.org},
-#' [_Tidy Models with R_](https://tmwr.org)
 #' @examples
+#' show_engines("gen_additive_mod")
 #'
-#' #show_engines("gen_additive_mod")
-#'
-#' #gen_additive_mod()
-#'
+#' gen_additive_mod()
 #'
 #' @export
 gen_additive_mod <- function(mode = "unknown",
                              select_features = NULL,
-                             adjust_deg_free = NULL) {
+                             adjust_deg_free = NULL,
+                             engine = "mgcv") {
 
   args <- list(
     select_features = rlang::enquo(select_features),
@@ -86,7 +47,7 @@ gen_additive_mod <- function(mode = "unknown",
     eng_args = NULL,
     mode     = mode,
     method   = NULL,
-    engine   = NULL
+    engine   = engine
   )
 
 }

R/gen_additive_mod_data.R

@@ -131,7 +131,7 @@ set_fit(
     protect = c("formula", "data"),
     func = c(pkg = "mgcv", fun = "gam"),
     defaults = list(
-      family = stats::binomial(link = "logit")
+      family = quote(stats::binomial(link = "logit"))
     )
   )
 )

R/gen_additive_mod_mgcv.R

@@ -0,0 +1,10 @@
+#' Generalized additive models via mgcv
+#'
+#' [mgcv::gam()] fits a generalized linear model with additive smoother terms
+#' for continuous predictors.
+#'
+#' @includeRmd man/rmd/gen_additive_mod_mgcv.Rmd details
+#'
+#' @name details_gen_additive_mod_mgcv
+#' @keywords internal
+NULL