documentation

Author: topepo

NEWS.md

@@ -1,5 +1,7 @@
 # parsnip (development version)
 
+* Enable generalized random forest (`grf`) models for classification, regression, and quantile regression modes. (#1288)
+
 # parsnip 1.3.3
 
 * Bug fix in how tunable parameters were configured for brulee neural networks. 

R/aaa_archive.R

@@ -1,4 +1,4 @@
-# no fmt
+# fmt: skip
 model_info_table <-
     tibble::tribble(
                       ~model,                 ~mode,            ~engine,            ~pkg,
@@ -21,6 +21,7 @@ model_info_table <-
                   "bag_tree",      "classification",            "rpart",      "baguette",
                       "bart",      "classification",           "dbarts",              NA,
                 "boost_tree",      "classification",             "C5.0",              NA,
+                "boost_tree",      "classification",         "catboost",        "bonsai",
                 "boost_tree",      "classification",              "h2o",          "agua",
                 "boost_tree",      "classification",          "h2o_gbm",          "agua",
                 "boost_tree",      "classification",         "lightgbm",        "bonsai",
@@ -69,6 +70,7 @@ model_info_table <-
                 "null_model",      "classification",          "parsnip",              NA,
                        "pls",      "classification",         "mixOmics",        "plsmod",
                "rand_forest",      "classification",            "aorsf",        "bonsai",
+               "rand_forest",      "classification",              "grf",              NA,
                "rand_forest",      "classification",              "h2o",          "agua",
                "rand_forest",      "classification",         "partykit",        "bonsai",
                "rand_forest",      "classification",     "randomForest",              NA,
@@ -82,11 +84,13 @@ model_info_table <-
                    "svm_rbf",      "classification",          "kernlab",              NA,
                    "svm_rbf",      "classification",        "liquidSVM",              NA,
                 "linear_reg", "quantile regression",         "quantreg",              NA,
+               "rand_forest", "quantile regression",              "grf",              NA,
                    "auto_ml",          "regression",              "h2o",          "agua",
                   "bag_mars",          "regression",            "earth",      "baguette",
                    "bag_mlp",          "regression",             "nnet",      "baguette",
                   "bag_tree",          "regression",            "rpart",      "baguette",
                       "bart",          "regression",           "dbarts",              NA,
+                "boost_tree",          "regression",         "catboost",        "bonsai",
                 "boost_tree",          "regression",              "h2o",          "agua",
                 "boost_tree",          "regression",          "h2o_gbm",          "agua",
                 "boost_tree",          "regression",         "lightgbm",        "bonsai",
@@ -130,6 +134,7 @@ model_info_table <-
                "poisson_reg",          "regression",       "stan_glmer", "multilevelmod",
                "poisson_reg",          "regression",         "zeroinfl",    "poissonreg",
                "rand_forest",          "regression",            "aorsf",        "bonsai",
+               "rand_forest",          "regression",              "grf",              NA,
                "rand_forest",          "regression",              "h2o",          "agua",
                "rand_forest",          "regression",         "partykit",        "bonsai",
                "rand_forest",          "regression",     "randomForest",              NA,
@@ -145,4 +150,3 @@ model_info_table <-
                    "svm_rbf",          "regression",          "kernlab",              NA,
                    "svm_rbf",          "regression",        "liquidSVM",              NA
       )
-

R/rand_forest_grf.R

@@ -0,0 +1,13 @@
+#' Random forests via grf
+#'
+#' The \pkg{grf} fits models that create a large number of decision
+#' trees, each independent of the others. The final prediction uses all
+#' predictions from the individual trees and combines them.
+#'
+#' @includeRmd man/rmd/rand_forest_grf.md details
+#'
+#' @name details_rand_forest_grf
+#' @keywords internal
+NULL
+
+# See inst/README-DOCS.md for a description of how these files are processed

man/augment.Rd

@@ -0,0 +1,105 @@
+```{r}
+#| child: aaa.Rmd
+#| include: false
+```
+
+`r descr_models("rand_forest", "grf")`
+
+## Tuning Parameters
+
+```{r}
+#| label: grf-param-info
+#| echo: false
+defaults <- 
+  tibble::tibble(parsnip = c("mtry", "trees", "min_n"),
+                 default = c("see below", "2000L", "5L"))
+
+param <-
+  rand_forest() |> 
+  set_engine("grf") |> 
+  make_parameter_list(defaults)
+```
+
+This model has `r nrow(param)` tuning parameters:
+
+```{r}
+#| label: grf-param-list
+#| echo: false
+#| results: asis
+param$item
+```
+
+`mtry` depends on the number of columns. If there are `p` predictors, the default value of `mtry` is `min(ceiling(sqrt(p) + 20), p)`. 
+
+## Translation from parsnip to the original package (regression)
+
+See [`?regression_forest`]("https://grf-labs.github.io/grf/reference/regression_forest.html)
+
+```{r}
+#| label: grf-reg
+rand_forest(
+  mtry = integer(1),
+  trees = integer(1),
+  min_n = integer(1)
+) |>  
+  set_engine("grf") |> 
+  set_mode("regression") |> 
+  translate()
+```
+
+## Translation from parsnip to the original package (classification)
+
+See [`?probability_forest`]("https://grf-labs.github.io/grf/reference/probability_forest.html)
+
+```{r}
+#| label: grf-cls
+rand_forest(
+  mtry = integer(1),
+  trees = integer(1),
+  min_n = integer(1)
+) |> 
+  set_engine("grf") |> 
+  set_mode("classification") |> 
+  translate()
+```
+
+## Translation from parsnip to the original package (quantile regression)
+
+See [`?quantile_forest`]("https://grf-labs.github.io/grf/reference/quantile_forest.html)
+
+When specifying _any_ quantile regression model, the user must specify the quantile levels _a priori_. 
+
+```{r}
+#| label: grf-quant
+rand_forest(
+  mtry = integer(1),
+  trees = integer(1),
+  min_n = integer(1)
+) |> 
+  set_engine("grf") |> 
+  set_mode("quantile regression", quantile_levels = (1:3) / 4) |> 
+  translate()
+```
+
+## Preprocessing requirements
+
+This method _does_ require qualitative predictors to be converted to a numeric format (manually). When using parsnip, a one-hot encoding is automatically used to do this. 
+
+## Other notes
+
+By default, parallel processing is turned off. When tuning, it is more efficient to parallelize over the resamples and tuning parameters. To parallelize the construction of the trees within the `grf` model, change the `num.threads` argument via [set_engine()]. 
+
+For `grf` confidence intervals, the intervals are constructed using the form `estimate +/- z * std_error`. For classification probabilities, these values can fall outside of  `[0, 1]` and will be coerced to be in this range.
+
+## Case weights
+
+The regression and classification models enable the use of case weights. The quantile regression mode does not. 
+
+## Examples 
+
+The "Fitting and Predicting with parsnip" article contains [examples](https://parsnip.tidymodels.org/articles/articles/Examples.html#rand-forest-grf) for `rand_forest()` with the `"grf"` engine.
+
+## References
+
+Athey, Susan, Julie Tibshirani, and Stefan Wager. "Generalized Random Forests". _Annals of Statistics_, 47(2), 2019.
+