documentation overhaul (#6)

describe more thoroughly what the _res_ objects are and the data they're predicting on.

Author: simonpcouch

R/predict.R

@@ -17,6 +17,8 @@
 #'
 #' @examples 
 #' \donttest{
+#' data(penguins_test)
+#' 
 #' # build and fit a regression model stack
 #' reg_st <-
 #'   stacks() %>%
@@ -25,8 +27,11 @@
 #'   stack_blend() %>%
 #'   stack_fit()
 #' 
-#' # predict on the penguins data
-#' predict(reg_st, penguins)
+#' # predict on the penguins testing data
+#' predict(reg_st, penguins_test)
+#' 
+#' # include the predictions from the members
+#' predict(reg_st, penguins_test, members = TRUE)
 #' 
 #' # build and fit a classification model stack
 #' class_st <-
@@ -38,8 +43,8 @@
 #' 
 #' # predict species, first as a class, then as
 #' # class probabilities
-#' predict(class_st, penguins)
-#' predict(class_st, penguins, type = "prob")
+#' predict(class_st, penguins_test)
+#' predict(class_st, penguins_test, type = "prob")
 #' }
 #'
 #' @importFrom stats predict

R/stack_add.R

@@ -20,19 +20,35 @@
 #' @template note_example_data
 #' 
 #' @examples 
-#' 
-#' # initialize a stack and add some candidate members
-#' st <- 
+#' \donttest{
+#' # put together a data stack using
+#' # tuning results for regression models
+#' reg_st <- 
 #'   stacks() %>%
 #'   stack_add(reg_res_lr) %>%
 #'   stack_add(reg_res_svm) %>%
 #'   stack_add(reg_res_sp)
 #'   
-#' # do the same with classification models
-#' st2 <- 
+#' # do the same with multinomial classification models
+#' class_st <-
 #'   stacks() %>%
 #'   stack_add(class_res_nn) %>%
-#'   stack_add(class_res_rf)  
+#'   stack_add(class_res_rf)
+#'   
+#' # ...or binomial classification models
+#' log_st <-
+#'   stacks() %>%
+#'   stack_add(log_res_nn) %>%
+#'   stack_add(log_res_rf)
+#'   
+#' # use custom names for each model:
+#' log_st2 <-
+#'   stacks() %>%
+#'   stack_add(log_res_nn, name = "neural_network") %>%
+#'   stack_add(log_res_rf, name = "random_forest")
+#' }
+#' 
+#' @family core verbs
 #' @export
 stack_add <- function(data_stack, candidates,
                            name = deparse(substitute(candidates)), ...) {

R/stack_blend.R

@@ -16,17 +16,32 @@
 #' @examples 
 #' \donttest{
 #' # put together a data stack
-#' st <- 
+#' reg_st <- 
 #'   stacks() %>%
 #'   stack_add(reg_res_lr) %>%
 #'   stack_add(reg_res_svm) %>%
 #'   stack_add(reg_res_sp)
-#'   
+#'
 #' # evaluate the data stack
-#' st %>%
+#' reg_st %>%
+#'   stack_blend()
+#'   
+#' # do the same with multinomial classification models
+#' class_st <-
+#'   stacks() %>%
+#'   stack_add(class_res_nn) %>%
+#'   stack_add(class_res_rf) %>%
+#'   stack_blend()
+#'   
+#' # ...or binomial classification models
+#' log_st <-
+#'   stacks() %>%
+#'   stack_add(log_res_nn) %>%
+#'   stack_add(log_res_rf) %>%
 #'   stack_blend()
 #' }
 #' 
+#' @family core verbs
 #' @export
 stack_blend <- function(data_stack, ...) {
   preds_formula <- 

R/stack_fit.R

@@ -23,18 +23,35 @@
 #' @examples 
 #' \donttest{
 #' # put together a data stack
-#' st <- 
+#' reg_st <- 
 #'   stacks() %>%
 #'   stack_add(reg_res_lr) %>%
 #'   stack_add(reg_res_svm) %>%
 #'   stack_add(reg_res_sp)
 #'
 #' # evaluate the data stack and fit the member models
-#' st %>%
+#' reg_st %>%
+#'   stack_blend() %>%
+#'   stack_fit()
+#'   
+#' # do the same with multinomial classification models
+#' class_st <-
+#'   stacks() %>%
+#'   stack_add(class_res_nn) %>%
+#'   stack_add(class_res_rf) %>%
+#'   stack_blend() %>%
+#'   stack_fit()
+#'   
+#' # ...or binomial classification models
+#' log_st <-
+#'   stacks() %>%
+#'   stack_add(log_res_nn) %>%
+#'   stack_add(log_res_rf) %>%
 #'   stack_blend() %>%
 #'   stack_fit()
 #' }
 #' 
+#' @family core verbs
 #' @export
 stack_fit <- function(model_stack, data = NULL, ...) {
 

R/stacks.R

@@ -13,7 +13,7 @@
 #' 
 #' @return A `data_stack` object.
 #' 
-#' @seealso [stack_add()]
+#' @family core verbs
 #' 
 #' @export
 stacks <- function(...) {

man-roxygen/note_example_data.R

@@ -1,7 +1,40 @@
 #' @section Example Data:
 #' 
-#' See \code{?example_data} to learn more about the \code{lin_reg_res}, 
-#' \code{reg_res_svm}, and \code{reg_res_sp} objects used in the examples below. 
-#' Long story short, they're resample objects outputted from 
-#' [tune::fit_resamples()] or [tune::tune_grid()] fitting \code{body_mass_g} 
-#' with all other variables in [palmerpenguins::penguins] as predictors!
+#' These examples make use of data and resampling objects exported with the
+#' package. All of them are derived from test cases making use of the
+#' `penguins` dataset from Allison Horst's `palmerpenguins` package. 
+#' 
+#' The `penguins_train` and `penguins_test` objects are subsets of the
+#' penguins data for using in training and testing, respectively.
+#' 
+#' Objects containing the substring `_res_` are `tune_results` objects
+#' for model specifications. The `reg` prefix indicates that the model
+#' definition is for use in regression, `class` indicates multinomial
+#' classification, and `log` (as in logistic) indicates binomial classification.
+#' The suffix indicates the model definition type. All of these `tune_results`
+#' objects are fitted on a 5-fold cross validation of the `penguins_train` data.
+#' 
+#' For the regression setting, these `tune_results` objects reflect
+#' models specified to fit `body_mass_g` using all of the other variables
+#' as predictors. These objects include:  
+#' 
+#' * `reg_res_lr`: Fitted resamples for a linear regression model
+#' * `reg_res_sp`: Tuning results for a splines model
+#' * `reg_res_svm`: Tuning results for a support vector machine model
+#' 
+#' In the multinomial classification setting, the relevant objects reflect 
+#' models specified to fit `island` using all of the other variables as 
+#' predictors. These objects include:
+#' 
+#' * `class_res_nn`: Fitted resamples for a neural network model
+#' * `class_res_rf`: Tuning results for a random forest model
+#' 
+#' In the binomial classification setting, the relevant objects reflect models
+#' specified to fit `sex` using all of the other variables as predictors. 
+#' These objects include:
+#' 
+#' * `log_res_nn`: Fitted resamples for a neural network model
+#' * `log_res_rf`: Tuning results for a random forest model
+#' 
+#' See \code{?example_data} to learn more about these objects, as well as browse
+#' the source code that generated them.