# Package 'parsnip' March 22, 2019 - The R Project for Statistical Computing

←

**Page content transcription**

If your browser does not render page correctly, please read the page content below

Package ‘parsnip’ March 22, 2019 Version 0.0.2 Title A Common API to Modeling and Analysis Functions Description A common interface is provided to allow users to specify a model without hav- ing to remember the different argument names across different functions or computa- tional engines (e.g. 'R', 'Spark', 'Stan', etc). Maintainer Max Kuhn URL https://tidymodels.github.io/parsnip BugReports https://github.com/tidymodels/parsnip/issues License GPL-2 Encoding UTF-8 LazyData true ByteCompile true VignetteBuilder knitr Depends R (¿= 2.10) Imports dplyr (¿= 0.8.0.1), rlang (¿= 0.3.1), purrr, utils, tibble (¿= 2.1.1), generics, glue, magrittr, stats, tidyr, globals Roxygen list(markdown = TRUE) RoxygenNote 6.1.1 Suggests testthat, knitr, rmarkdown, survival, keras, xgboost, covr, C50, 1

2 R topics documented: sparklyr (¿= 1.0.0), earth, glmnet, kernlab, kknn, randomForest, ranger, rpart, MASS, nlme R topics documented: boost tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 C5.0 train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 check times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 decision tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 fit.model spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 fit control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 keras mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 lending club . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 linear reg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 logistic reg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 mars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 mlp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 model fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 model spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 multinom reg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 multi predict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 nearest neighbor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 nullmodel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 null model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 predict.model fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 rand forest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 rpart train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 set args . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 set engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 surv reg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 svm poly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 svm rbf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 tidy.model fit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 translate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 varying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 varying args.model spec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 wa churn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 xgb train . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Index 47

boost tree 3 boost tree General Interface for Boosted Trees Description boost tree() is a way to generate a specification of a model before fitting and allows the model to be created using different packages in R or via Spark. The main arguments for the model are: mtry: The number of predictors that will be randomly sampled at each split when creating the tree models. trees: The number of trees contained in the ensemble. min n: The minimum number of data points in a node that are required for the node to be split further. tree depth: The maximum depth of the tree (i.e. number of splits). learn rate: The rate at which the boosting algorithm adapts from iteration-to-iteration. loss reduction: The reduction in the loss function required to split further. sample size: The amount of data exposed to the fitting routine. These arguments are converted to their specific names at the time that the model is fit. Other options and argument can be set using the set engine() function. If left to their de- faults 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. Usage boost_tree(mode = "unknown", mtry = NULL, trees = NULL, min_n = NULL, tree_depth = NULL, learn_rate = NULL, loss_reduction = NULL, sample_size = NULL) ## S3 method for class 'boost_tree' update(object, mtry = NULL, trees = NULL, min_n = NULL, tree_depth = NULL, learn_rate = NULL, loss_reduction = NULL, sample_size = NULL, fresh = FALSE, ...) Arguments mode A single character string for the type of model. Possible values for this model are ”unknown”, ”regression”, or ”classification”. mtry An number for the number (or proportion) of predictors that will be randomly sampled at each split when creating the tree models (xgboost only). trees An integer for the number of trees contained in the ensemble. min n An integer for the minimum number of data points in a node that are required for the node to be split further. tree depth An integer for the maximum deopth of the tree (i.e. number of splits) (xgboost only). learn rate A number for the rate at which the boosting algorithm adapts from iteration-to-iteration (xgboost only).

4 boost tree loss reduction A number for the reduction in the loss function required to split further (xgboost only). sample size An number for the number (or proportion) of data that is exposed to the fitting routine. For xgboost, the sampling is done at at each iteration while C5.0 samples once during traning. object A boosted tree model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). Details The data given to the function are not saved and are only used to determine the mode of the model. For boost tree(), the possible modes are ”regression” and ”classification”. The model can be created using the fit() function using the following engines: R: "xgboost", "C5.0" Spark: "spark" Value An updated model specification. Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: xgboost classification parsnip::xgb_train(x = missing_arg(), y = missing_arg(), nthread = 1, verbose = 0) xgboost regression parsnip::xgb_train(x = missing_arg(), y = missing_arg(), nthread = 1, verbose = 0) C5.0 classification parsnip::C5.0_train(x = missing_arg(), y = missing_arg(), weights = missing_arg()) spark classification sparklyr::ml_gradient_boosted_trees(x = missing_arg(), formula = missing_arg(), type = "classification", seed = sample.int(10ˆ5, 1)) spark regression sparklyr::ml_gradient_boosted_trees(x = missing_arg(), formula = missing_arg(), type = "regression", seed = sample.int(10ˆ5, 1))

C5.0 train 5 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. See Also varying(), fit(), set engine() Examples boost_tree(mode = "classification", trees = 20) # Parameters can be represented by a placeholder: boost_tree(mode = "regression", mtry = varying()) model

6 check times sample A value between (0, .999) that specifies the random proportion of the data should be used to train the model. By default, all the samples are used for model training. Samples not used for training are used to evaluate the accuracy of the model in the printed output. ... Other arguments to pass. Value A fitted C5.0 model. check times Execution Time Data Description These data were collected from the CRAN web page for 13,626 R packages. The time to complete the standard package checking routine was collected In some cases, the package checking process is stopped due to errors and these data are treated as censored. It is less than 1 percent. Details As predictors, the associated package source code were downloaded and parsed to create predictors, including authors: The number of authors in the author field. imports: The number of imported packages. suggests: The number of packages suggested. depends: The number of hard dependencies. Roxygen: a binary indicator for whether Roxygen was used for documentation. gh: a binary indicator for whether the URL field contained a GitHub link. rforge: a binary indicator for whether the URL field contained a link to R-forge. descr: The number of characters (or, in some cases, bytes) in the description field. r count: The number of R files in the R directory. r size: The total disk size of the R files. ns import: Estimated number of imported functions or methods. ns export: Estimated number of exported functions or methods. s3 methods: Estimated number of S3 methods. s4 methods: Estimated number of S4 methods. doc count: How many Rmd or Rnw files in the vignettes directory. doc size: The disk size of the Rmd or Rnw files. src count: The number of files in the src directory. src size: The size on disk of files in the src directory. data count The number of files in the data directory. data size: The size on disk of files in the data directory.

decision tree 7 testthat count: The number of files in the testthat directory. testthat size: The size on disk of files in the testthat directory. check time: The time (in seconds) to run R CMD check using the ”r-devel-windows- ix86+x86 64‘ flavor. status: An indicator for whether the tests completed. Data were collected on 2019-01-20. Value check times a data frame Source CRAN Examples data(check_times) str(check_times) decision tree General Interface for Decision Tree Models Description decision tree() is a way to generate a specification of a model before fitting and allows the model to be created using different packages in R or via Spark. The main arguments for the model are: cost complexity: The cost/complexity parameter (a.k.a. Cp) used by CART models (rpart only). tree depth: The maximum depth of a tree (rpart and spark only). min n: The minimum number of data points in a node that are required for the node to be split further. These arguments are converted to their specific names at the time that the model is fit. Other options and argument 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. Usage decision_tree(mode = "unknown", cost_complexity = NULL, tree_depth = NULL, min_n = NULL) ## S3 method for class 'decision_tree' update(object, cost_complexity = NULL, tree_depth = NULL, min_n = NULL, fresh = FALSE, ...)

8 decision tree Arguments mode A single character string for the type of model. Possible values for this model are ”unknown”, ”regression”, or ”classification”. cost complexity A positive number for the the cost/complexity parameter (a.k.a. Cp) used by CART models (rpart only). tree depth An integer for maximum depth of the tree. min n An integer for the minimum number of data points in a node that are required for the node to be split further. object A random forest model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). Details The model can be created using the fit() function using the following engines: R: "rpart" or "C5.0" (classification only) Spark: "spark" Note that, for rpart models, but cost complexity and tree depth can be both be specified but the package will give precedence to cost complexity. Also, tree depth values greater than 30 rpart will give nonsense results on 32-bit machines. Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are:: rpart classification rpart::rpart(formula = missing_arg(), data = missing_arg(), weights = missing_arg()) rpart regression rpart::rpart(formula = missing_arg(), data = missing_arg(), weights = missing_arg()) C5.0 classification parsnip::C5.0_train(x = missing_arg(), y = missing_arg(), weights = missing_arg(), trials = 1) spark classification sparklyr::ml_decision_tree_classifier(x = missing_arg(), formula = missing_arg(), seed = sample.int(10ˆ5, 1), type = "classification") spark regression sparklyr::ml_decision_tree_classifier(x = missing_arg(), formula = missing_arg(), seed = sample.int(10ˆ5, 1), type = "regression")

descriptors 9 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. See Also varying(), fit() Examples decision_tree(mode = "classification", tree_depth = 5) # Parameters can be represented by a placeholder: decision_tree(mode = "regression", cost_complexity = varying()) model

10 descriptors Details Existing functions: .obs(): The current number of rows in the data set. .preds(): The number of columns in the data set that are associated with the predic- tors prior to dummy variable creation. .cols(): The number of predictor columns availible after dummy variables are created (if any). .facts(): The number of factor predictors in the dat set. .lvls(): If the outcome is a factor, this is a table with the counts for each level (and NA otherwise). .x(): The predictors returned in the format given. Either a data frame or a matrix. .y(): The known outcomes returned in the format given. Either a vector, matrix, or data frame. .dat(): A data frame containing all of the predictors and the outcomes. If fit xy() was used, the outcomes are attached as the column, ..y. For example, if you use the model formula Sepal.Width ˜ . with the iris data, the values would be .preds() = 4 (the 4 columns in `iris`) .cols() = 5 (3 numeric columns + 2 from Species dummy variables) .obs() = 150 .lvls() = NA (no factor outcome) .facts() = 1 (the Species predictor) .y() = (Sepal.Width as a vector) .x() = (The other 4 columns as a data frame) .dat() = (The full data set) If the formula Species ˜ . where used: .preds() = 4 (the 4 numeric columns in `iris`) .cols() = 4 (same) .obs() = 150 .lvls() = c(setosa = 50, versicolor = 50, virginica = 50) .facts() = 0 .y() = (Species as a vector) .x() = (The other 4 columns as a data frame) .dat() = (The full data set) To use these in a model fit, pass them to a model specification. The evaluation is delayed until the time when the model is run via fit() (and the variables listed above are available). For example: data("lending_club") rand_forest(mode = "classification", mtry = .cols() - 2) When no descriptors are found, the computation of the descriptor values is not executed.

fit.model spec 11 fit.model spec Fit a Model Specification to a Dataset Description fit() and fit xy() take a model specification, translate the required code by substituting arguments, and execute the model fit routine. Usage ## S3 method for class 'model_spec' fit(object, formula = NULL, data = NULL, control = fit_control(), ...) ## S3 method for class 'model_spec' fit_xy(object, x = NULL, y = NULL, control = fit_control(), ...) Arguments object An object of class model spec that has a chosen engine (via set engine()). formula An object of class ”formula” (or one that can be coerced to that class): a symbolic description of the model to be fitted. data Optional, depending on the interface (see Details below). A data frame containing all relevant variables (e.g. outcome(s), predictors, case weights, etc). Note: when needed, a named argument should be used. control A named list with elements verbosity and catch. See fit control(). ... Not currently used; values passed here will be ignored. Other options required to fit the model should be passed using set engine(). x A matrix or data frame of predictors. y A vector, matrix or data frame of outcome data. Details fit() and fit xy() substitute the current arguments in the model specification into the computational engine’s code, checks them for validity, then fits the model using the data and the engine-specific code. Different model functions have different interfaces (e.g. formula or x/y) and these functions translate between the interface used when fit() or fit xy() were invoked and the one required by the underlying model. When possible, these functions attempt to avoid making copies of the data. For example, if the underlying model uses a formula and fit() is invoked, the original data are references when the model is fit. However, if the underlying model uses something else, such as x/y, the formula is evaluated and the data are converted to the required format. In this case, any calls in the resulting model objects reference the temporary objects used to fit the model.

12 fit control Value A model fit object that contains several elements: lvl: If the outcome is a factor, this contains the factor levels at the time of model fitting. spec: The model specification object (object in the call to fit) fit: when the model is executed without error, this is the model object. Otherwise, it is a try-error object with the error message. preproc: any objects needed to convert between a formula and non-formula interface (such as the terms object) The return value will also have a class related to the fitted model (e.g. " glm") before the base class of "model fit". See Also set engine(), fit control(), model spec, model fit Examples # Although `glm()` only has a formula interface, different # methods for specifying the model can be used library(dplyr) data("lending_club") lr_mod % fit_xy(x = lending_club[, c("funded_amnt", "int_rate")], y = lending_club$Class) using_formula using_xy fit control Control the fit function Description Options can be passed to the fit() function that control the output and computations Usage fit_control(verbosity = 1L, catch = FALSE)

keras mlp 13 Arguments verbosity An integer where a value of zero indicates that no messages or output should be shown when packages are loaded or when the model is fit. A value of 1 means that package loading is quiet but model fits can produce output to the screen (depending on if they contain their own verbose- type argument). A value of 2 or more indicates that any output should be seen. catch A logical where a value of TRUE will evaluate the model inside of try(,silent = TRUE). If the model fails, an object is still returned (without an error) that inherits the class ”try-error”. Value An S3 object with class ”fit control” that is a named list with the results of the function call keras mlp Simple interface to MLP models via keras Description Instead of building a keras model sequentially, keras mlp can be used to create a feed- forward network with a single hidden layer. Regularization is via either weight decay or dropout. Usage keras_mlp(x, y, hidden_units = 5, decay = 0, dropout = 0, epochs = 20, act = "softmax", seeds = sample.int(10ˆ5, size = 3), ...) Arguments x A data frame or matrix of predictors y A vector (factor or numeric) or matrix (numeric) of outcome data. hidden units An integer for the number of hidden units. decay A non-negative real number for the amount of weight decay. Either this parameter or dropout can specified. dropout The proportion of parameters to set to zero. Either this parameter or decay can specified. epochs An integer for the number of passes through the data. act A character string for the type of activation function between layers. seeds A vector of three positive integers to control randomness of the calcula- tions. ... Currently ignored. Value A keras model object.

14 linear reg lending club Loan Data Description Loan Data Details These data were downloaded from the Lending Club access site (see below) and are from the first quarter of 2016. A subset of the rows and variables are included here. The outcome is in the variable Class and is either ”good” (meaning that the loan was fully paid back or currently on-time) or ”bad” (charged off, defaulted, of 21-120 days late). A data dictionary can be found on the source website. Value lending club a data frame Source Lending Club Statistics https://www.lendingclub.com/info/download-data.action Examples data(lending_club) str(lending_club) linear reg General Interface for Linear Regression Models Description 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: penalty: The total amount of regularization in the model. Note that this must be zero for some engines. mixture: The proportion of L1 regularization in the model. 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 argument 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.

linear reg 15 Usage linear_reg(mode = "regression", penalty = NULL, mixture = NULL) ## S3 method for class 'linear_reg' update(object, penalty = NULL, mixture = NULL, fresh = FALSE, ...) Arguments mode A single character string for the type of model. The only possible value for this model is ”regression”. penalty An 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). mixture A number between zero and one (inclusive) that represents the proportion of regularization that is used for the L2 penalty (i.e. weight decay, or ridge regression) versus L1 (the lasso) (glmnet and spark only). object A linear regression model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). 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: R: "lm" or "glmnet" Stan: "stan" Spark: "spark" keras: "keras" Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: lm stats::lm(formula = missing_arg(), data = missing_arg(), weights = missing_arg()) glmnet glmnet::glmnet(x = missing_arg(), y = missing_arg(), weights = missing_arg(), family = "gaussian") stan

16 linear reg rstanarm::stan_glm(formula = missing_arg(), data = missing_arg(), weights = missing_arg(), family = stats::gaussian) spark sparklyr::ml_linear_regression(x = missing_arg(), formula = missing_arg(), weight_col = missing_arg()) keras parsnip::keras_mlp(x = missing_arg(), y = missing_arg(), hidden_units = 1, act = "linear") When using glmnet models, there is the option to pass multiple values (or no values) to the penalty argument. This can have an effect on the model object results. When using the predict() method in these cases, the return value depends on the value of penalty. When using predict(), only a single value of the penalty can be used. When predicting on multiple penalties, the multi predict() function can be used. It returns a tibble with a list column called .pred that contains a tibble with all of the penalty results. For prediction, the stan engine can compute posterior intervals analogous to confidence and prediction intervals. In these instances, the units are the original outcome and when std error = TRUE, the standard deviation of the posterior distribution (or posterior predic- tive distribution as appropriate) is returned. 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. See Also varying(), fit(), set engine() Examples linear_reg() # Parameters can be represented by a placeholder: linear_reg(penalty = varying()) model

logistic reg 17 logistic reg General Interface for Logistic Regression Models Description logistic 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: penalty: The total amount of regularization in the model. Note that this must be zero for some engines. mixture: The proportion of L1 regularization in the model. 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 argument 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. Usage logistic_reg(mode = "classification", penalty = NULL, mixture = NULL) ## S3 method for class 'logistic_reg' update(object, penalty = NULL, mixture = NULL, fresh = FALSE, ...) Arguments mode A single character string for the type of model. The only possible value for this model is ”classification”. penalty An 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). mixture A number between zero and one (inclusive) that represents the proportion of regularization that is used for the L2 penalty (i.e. weight decay, or ridge regression) versus L1 (the lasso) (glmnet and spark only). object A logistic regression model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). Details For logistic reg(), the mode will always be ”classification”. The model can be created using the fit() function using the following engines: R: "glm" or "glmnet" Stan: "stan" Spark: "spark" keras: "keras"

18 logistic reg Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: glm stats::glm(formula = missing_arg(), data = missing_arg(), weights = missing_arg(), family = stats::binomial) glmnet glmnet::glmnet(x = missing_arg(), y = missing_arg(), weights = missing_arg(), family = "binomial") stan rstanarm::stan_glm(formula = missing_arg(), data = missing_arg(), weights = missing_arg(), family = stats::binomial) spark sparklyr::ml_logistic_regression(x = missing_arg(), formula = missing_arg(), weight_col = missing_arg(), family = "binomial") keras parsnip::keras_mlp(x = missing_arg(), y = missing_arg(), hidden_units = 1, act = "linear") When using glmnet models, there is the option to pass multiple values (or no values) to the penalty argument. This can have an effect on the model object results. When using the predict() method in these cases, the return value depends on the value of penalty. When using predict(), only a single value of the penalty can be used. When predicting on multiple penalties, the multi predict() function can be used. It returns a tibble with a list column called .pred that contains a tibble with all of the penalty results. For prediction, the stan engine can compute posterior intervals analogous to confidence and prediction intervals. In these instances, the units are the original outcome and when std error = TRUE, the standard deviation of the posterior distribution (or posterior predic- tive distribution as appropriate) is returned. For glm, the standard error is in logit units while the intervals are in probability units. 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.

mars 19 See Also varying(), fit() Examples logistic_reg() # Parameters can be represented by a placeholder: logistic_reg(penalty = varying()) model

20 mlp Details The model can be created using the fit() function using the following engines: R: "earth" Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: earth classification earth::earth(x = missing_arg(), y = missing_arg(), weights = missing_arg(), glm = list(family = stats::binomial), keepxy = TRUE) earth regression earth::earth(x = missing_arg(), y = missing_arg(), weights = missing_arg(), keepxy = TRUE) Note that, when the model is fit, the earth package only has its namespace loaded. However, if multi predict is used, the package is attached. See Also varying(), fit() Examples mars(mode = "regression", num_terms = 5) model

mlp 21 Usage mlp(mode = "unknown", hidden_units = NULL, penalty = NULL, dropout = NULL, epochs = NULL, activation = NULL) ## S3 method for class 'mlp' update(object, hidden_units = NULL, penalty = NULL, dropout = NULL, epochs = NULL, activation = NULL, fresh = FALSE, ...) Arguments mode A single character string for the type of model. Possible values for this model are ”unknown”, ”regression”, or ”classification”. hidden units An integer for the number of units in the hidden model. penalty A non-negative numeric value for the amount of weight decay. dropout A number between 0 (inclusive) and 1 denoting the proportion of model parameters randomly set to zero during model training. epochs An integer for the number of training iterations. activation A single character strong denoting the type of relationship between the original predictors and the hidden unit layer. The activation function between the hidden and output layers is automatically set to either ”lin- ear” or ”softmax” depending on the type of outcome. Possible values are: ”linear”, ”softmax”, ”relu”, and ”elu” object A random forest model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). Details These arguments are converted to their specific names at the time that the model is fit. Other options and argument can be set using set engine(). If left to their defaults here (see above), the values are taken from the underlying model functions. One exception is hidden units when nnet::nnet is used; that function’s size argument has no default so a value of 5 units will be used. Also, unless otherwise specified, the linout argument to nnet::nnet() will be set to TRUE when a regression model is created. If parameters need to be modified, update() can be used in lieu of recreating the object from scratch. The model can be created using the fit() function using the following engines: R: "nnet" keras: "keras" An error is thrown if both penalty and dropout are specified for keras models. Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: keras classification

22 model fit parsnip::keras_mlp(x = missing_arg(), y = missing_arg()) keras regression parsnip::keras_mlp(x = missing_arg(), y = missing_arg()) nnet classification nnet::nnet(formula = missing_arg(), data = missing_arg(), weights = missing_arg(), size = 5, trace = FALSE, linout = FALSE) nnet regression nnet::nnet(formula = missing_arg(), data = missing_arg(), weights = missing_arg(), size = 5, trace = FALSE, linout = TRUE) See Also varying(), fit() Examples mlp(mode = "classification", penalty = 0.01) # Parameters can be represented by a placeholder: mlp(mode = "regression", hidden_units = varying()) model

model spec 23 As discussed in the documentation for model spec, the original arguments to the specifica- tion are saved as quosures. These are evaluated for the model fit object prior to fitting. If the resulting model object prints its call, any user-defined options are shown in the call preceded by a tilde (see the example below). This is a result of the use of quosures in the specification. This class and structure is the basis for how parsnip stores model objects after to seeing the data and applying a model. Examples # Keep the `x` matrix if the data are not too big. spec_obj % set_engine("lm", x = ifelse(.obs() < 500, TRUE, FALSE)) spec_obj fit_obj

24 model spec Argument Details An important detail to understand when creating model specifications is that they are intended to be functionally independent of the data. While it is true that some tuning parameters are data dependent, the model specification does not interact with the data at all. For example, most R functions immediately evaluate their arguments. For example, when calling mean(dat vec), the object dat vec is immediately evaluated inside of the function. parsnip model functions do not do this. For example, using rand_forest(mtry = ncol(iris) - 1) does not execute ncol(iris) -1 when creating the specification. This can be seen in the output: > rand_forest(mtry = ncol(iris) - 1) Random Forest Model Specification (unknown) Main Arguments: mtry = ncol(iris) - 1 The model functions save the argument expressions and their associated environments (a.k.a. a quosure) to be evaluated later when either fit() or fit xy() are called with the actual data. The consequence of this strategy is that any data required to get the parameter values must be available when the model is fit. The two main ways that this can fail is if: 1. The data have been modified between the creation of the model specification and when the model fit function is invoked. 2. If the model specification is saved and loaded into a new session where those same data objects do not exist. The best way to avoid these issues is to not reference any data objects in the global envi- ronment but to use data descriptors such as .cols(). Another way of writing the previous specification is rand_forest(mtry = .cols() - 1) This is not dependent on any specific data object and is evaluated immediately before the model fitting process begins. One less advantageous approach to solving this issue is to use quasiquotation. This would insert the actual R object into the model specification and might be the best idea when the data object is small. For example, using rand_forest(mtry = ncol(!!iris) - 1) would work (and be reproducible between sessions) but embeds the entire iris data set into the mtry expression:

multinom reg 25 > rand_forest(mtry = ncol(!!iris) - 1) Random Forest Model Specification (unknown) Main Arguments: mtry = ncol(structure(list(Sepal.Length = c(5.1, 4.9, 4.7, 4.6, 5, However, if there were an object with the number of columns in it, this wouldn’t be too bad: > mtry_val mtry_val [1] 4 > rand_forest(mtry = !!mtry_val) Random Forest Model Specification (unknown) Main Arguments: mtry = 4 More information on quosures and quasiquotation can be found at https://tidyeval. tidyverse.org. multinom reg General Interface for Multinomial Regression Models Description multinom 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, keras, or Spark. The main arguments for the model are: penalty: The total amount of regularization in the model. Note that this must be zero for some engines. mixture: The proportion of L1 regularization in the model. 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 argument 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. Usage multinom_reg(mode = "classification", penalty = NULL, mixture = NULL) ## S3 method for class 'multinom_reg' update(object, penalty = NULL, mixture = NULL, fresh = FALSE, ...)

26 multinom reg Arguments mode A single character string for the type of model. The only possible value for this model is ”classification”. penalty An 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). mixture A number between zero and one (inclusive) that represents the proportion of regularization that is used for the L2 penalty (i.e. weight decay, or ridge regression) versus L1 (the lasso) (glmnet only). object A multinomial regression model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). Details For multinom reg(), the mode will always be ”classification”. The model can be created using the fit() function using the following engines: R: "glmnet" Stan: "stan" keras: "keras" Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: glmnet glmnet::glmnet(x = missing_arg(), y = missing_arg(), weights = missing_arg(), family = "multinomial") spark sparklyr::ml_logistic_regression(x = missing_arg(), formula = missing_arg(), weight_col = missing_arg(), family = "multinomial") keras parsnip::keras_mlp(x = missing_arg(), y = missing_arg(), hidden_units = 1, act = "linear") When using glmnet models, there is the option to pass multiple values (or no values) to the penalty argument. This can have an effect on the model object results. When using the predict() method in these cases, the return value depends on the value of penalty. When using predict(), only a single value of the penalty can be used. When predicting on multiple penalties, the multi predict() function can be used. It returns a tibble with a list column called .pred that contains a tibble with all of the penalty results.

multi predict 27 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. See Also varying(), fit() Examples multinom_reg() # Parameters can be represented by a placeholder: multinom_reg(penalty = varying()) model

28 nearest neighbor nearest neighbor General Interface for K-Nearest Neighbor Models Description nearest neighbor() is a way to generate a specification of a model before fitting and allows the model to be created using different packages in R. The main arguments for the model are: neighbors: The number of neighbors considered at each prediction. weight func: The type of kernel function that weights the distances between samples. dist power: The parameter used when calculating the Minkowski distance. This cor- responds to the Manhattan distance with dist power = 1 and the Euclidean distance with dist power = 2. These arguments are converted to their specific names at the time that the model is fit. Other options and argument 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. Usage nearest_neighbor(mode = "unknown", neighbors = NULL, weight_func = NULL, dist_power = NULL) Arguments mode A single character string for the type of model. Possible values for this model are "unknown", "regression", or "classification". neighbors A single integer for the number of neighbors to consider (often called k). weight func A single character for the type of kernel function used to weight distances between samples. Valid choices are: "rectangular", "triangular", "epanechnikov", "biweight", "triweight", "cos", "inv", "gaussian", "rank", or "optimal". dist power A single number for the parameter used in calculating Minkowski distance. Details The model can be created using the fit() function using the following engines: R: "kknn" Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: kknn (classification or regression) kknn::train.kknn(formula = missing_arg(), data = missing_arg(), kmax = missing_arg())

nullmodel 29 Note For kknn, the underlying modeling function used is a restricted version of train.kknn() and not kknn(). It is set up in this way so that parsnip can utilize the underlying predict.train.kknn method to predict on new data. This also means that a single value of that function’s kernel argument (a.k.a weight func here) can be supplied See Also varying(), fit() Examples nearest_neighbor(neighbors = 11) nullmodel Fit a simple, non-informative model Description Fit a single mean or largest class model. nullmodel() is the underlying computational function for the null model() specification. Usage nullmodel(x, ...) ## Default S3 method: nullmodel(x = NULL, y, ...) ## S3 method for class 'nullmodel' print(x, ...) ## S3 method for class 'nullmodel' predict(object, new_data = NULL, type = NULL, ...) Arguments x An optional matrix or data frame of predictors. These values are not used in the model fit ... Optional arguments (not yet used) y A numeric vector (for regression) or factor (for classification) of outcomes object An object of class nullmodel new data A matrix or data frame of predictors (only used to determine the number of predictions to return) type Either ”raw” (for regression), ”class” or ”prob” (for classification)

30 null model Details nullmodel() emulates other model building functions, but returns the simplest model pos- sible given a training set: a single mean for numeric outcomes and the most prevalent class for factor outcomes. When class probabilities are requested, the percentage of the training set samples with the most prevalent class is returned. Value The output of nullmodel() is a list of class nullmodel with elements call the function call value the mean of y or the most prevalent class levels when y is a factor, a vector of levels. NULL otherwise pct when y is a factor, a data frame with a column for each class (NULL otherwise). The column for the most prevalent class has the proportion of the training samples with that class (the other columns are zero). n the number of elements in y predict.nullmodel() returns a either a factor or numeric vector depending on the class of y. All predictions are always the same. Examples outcome

predict.model fit 31 Details The model can be created using the fit() function using the following engines: R: "parsnip" Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are: parsnip classification nullmodel(x = missing_arg(), y = missing_arg()) parsnip regression nullmodel(x = missing_arg(), y = missing_arg()) See Also varying(), fit() Examples null_model(mode = "regression") predict.model fit Model predictions Description Apply a model to create different types of predictions. predict() can be used for all types of models and used the ”type” argument for more specificity. Usage ## S3 method for class 'model_fit' predict(object, new_data, type = NULL, opts = list(), ...) Arguments object An object of class model fit new data A rectangular data object, such as a data frame. type A single character value or NULL. Possible values are ”numeric”, ”class”, ”prob”, ”conf int”, ”pred int”, ”quantile”, or ”raw”. When NULL, predict() will choose an appropriate value based on the model’s mode. opts A list of optional arguments to the underlying predict function that will be used when type = "raw". The list should not include options for the model object or the new data being predicted.

32 predict.model fit ... Arguments to the underlying model’s prediction function cannot be passed here (see opts). There are some parsnip related options that can be passed, depending on the value of type. Possible arguments are: level: for types of ”conf int” and ”pred int” this is the parameter for the tail area of the intervals (e.g. confidence level for confidence intervals). Default value is 0.95. std error: add the standard error of fit or prediction for types of ”conf int” and ”pred int”. Default value is FALSE. quantile: the quantile(s) for quantile regression (not implemented yet) time: the time(s) for hazard probability estimates (not implemented yet) Details If ”type” is not supplied to predict(), then a choice is made (type = "numeric" for regres- sion models and type = "class" for classification). predict() is designed to provide a tidy result (see ”Value” section below) in a tibble output format. When using type = "conf int" and type = "pred int", the options level and std error can be used. The latter is a logical for an extra column of standard error values (if available). Value With the exception of type = "raw", the results of predict.model fit() will be a tibble as many rows in the output as there are rows in new data and the column names will be predictable. For numeric results with a single outcome, the tibble will have a .pred column and .pred Yname for multivariate results. For hard class predictions, the column is named .pred class and, when type = "prob", the columns are .pred classlevel. type = "conf int" and type = "pred int" return tibbles with columns .pred lower and .pred upper with an attribute for the confidence level. In the case where intervals can be produces for class probabilities (or other non-scalar outputs), the columns will be named .pred lower classlevel and so on. Quantile predictions return a tibble with a column .pred, which is a list-column. Each list element contains a tibble with columns .pred and .quantile (and perhaps other columns). Using type = "raw" with predict.model fit() will return the unadulterated results of the prediction function. In the case of Spark-based models, since table columns cannot contain dots, the same convention is used except 1) no dots appear in names and 2) vectors are never returned but type-specific prediction functions. When the model fit failed and the error was captured, the predict() function will return the same structure as above but filled with missing values. This does not currently work for multivariate models. Examples library(dplyr)

rand forest 33 lm_model % set_engine("lm") %>% fit(mpg ˜ ., data = mtcars %>% slice(11:32)) pred_cars % slice(1:10) %>% select(-mpg) predict(lm_model, pred_cars) predict( lm_model, pred_cars, type = "conf_int", level = 0.90 ) predict( lm_model, pred_cars, type = "raw", opts = list(type = "terms") ) rand forest General Interface for Random Forest Models Description rand forest() is a way to generate a specification of a model before fitting and allows the model to be created using different packages in R or via Spark. The main arguments for the model are: mtry: The number of predictors that will be randomly sampled at each split when creating the tree models. trees: The number of trees contained in the ensemble. min n: The minimum number of data points in a node that are required for the node to be split further. These arguments are converted to their specific names at the time that the model is fit. Other options and argument 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. Usage rand_forest(mode = "unknown", mtry = NULL, trees = NULL, min_n = NULL) ## S3 method for class 'rand_forest' update(object, mtry = NULL, trees = NULL, min_n = NULL, fresh = FALSE, ...)

34 rand forest Arguments mode A single character string for the type of model. Possible values for this model are ”unknown”, ”regression”, or ”classification”. mtry An integer for the number of predictors that will be randomly sampled at each split when creating the tree models. trees An integer for the number of trees contained in the ensemble. min n An integer for the minimum number of data points in a node that are required for the node to be split further. object A random forest model specification. fresh A logical for whether the arguments should be modified in-place of or replaced wholesale. ... Not used for update(). Details The model can be created using the fit() function using the following engines: R: "ranger" or "randomForest" Spark: "spark" Engine Details Engines may have pre-set default arguments when executing the model fit call. For this type of model, the template of the fit calls are:: ranger classification ranger::ranger(formula = missing_arg(), data = missing_arg(), case.weights = missing_arg(), num.threads = 1, verbose = FALSE, seed = sample.int(10ˆ5, 1), probability = TRUE) ranger regression ranger::ranger(formula = missing_arg(), data = missing_arg(), case.weights = missing_arg(), num.threads = 1, verbose = FALSE, seed = sample.int(10ˆ5, 1)) randomForests classification randomForest::randomForest(x = missing_arg(), y = missing_arg()) randomForests regression randomForest::randomForest(x = missing_arg(), y = missing_arg()) spark classification sparklyr::ml_random_forest(x = missing_arg(), formula = missing_arg(), type = "classification", seed = sample.int(10ˆ5, 1)) spark regression

rpart train 35 sparklyr::ml_random_forest(x = missing_arg(), formula = missing_arg(), type = "regression", seed = sample.int(10ˆ5, 1)) For ranger 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. 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. See Also varying(), fit() Examples rand_forest(mode = "classification", trees = 2000) # Parameters can be represented by a placeholder: rand_forest(mode = "regression", mtry = varying()) model

36 set args cp A non-negative number for complexity parameter. Any split that does not decrease the overall lack of fit by a factor of cp is not attempted. For instance, with anova splitting, this means that the overall R-squared must increase by cp at each step. The main role of this parameter is to save computing time by pruning off splits that are obviously not worthwhile. Essentially,the user informs the program that any split which does not improve the fit by cp will likely be pruned off by cross-validation, and that hence the program need not pursue it. minsplit An integer for the minimum number of observations that must exist in a node in order for a split to be attempted. maxdepth An integer for the maximum depth of any node of the final tree, with the root node counted as depth 0. Values greater than 30 rpart will give nonsense results on 32-bit machines. This function will truncate maxdepth to 30 in those cases. ... Other arguments to pass to either rpart or rpart.control. Value A fitted rpart model. set args Change elements of a model specification Description set args() can be used to modify the arguments of a model specification while set mode() is used to change the model’s mode. Usage set_args(object, ...) set_mode(object, mode) Arguments object A model specification. ... One or more named model arguments. mode A character string for the model type (e.g. ”classification” or ”regres- sion”) Details set args() will replace existing values of the arguments. Value An updated model object.

set engine 37 Examples rand_forest() rand_forest() %>% set_args(mtry = 3, importance = TRUE) %>% set_mode("regression") set engine Declare a computational engine and specific arguments Description set engine() is used to specify which package or system will be used to fit the model, along with any arguments specific to that software. Usage set_engine(object, engine, ...) Arguments object A model specification. engine A character string for the software that should be used to fit the model. This is highly dependent on the type of model (e.g. linear regression, random forest, etc.). ... Any optional arguments associated with the chosen computational engine. These are captured as quosures and can be varying(). Value An updated model specification. Examples # First, set general arguments using the standardized names mod % # now say how you want to fit the model and another other options set_engine("glmnet", nlambda = 10) translate(mod, engine = "glmnet")

You can also read