# parsnip

## Introduction

The goal of parsnip is to provide a tidy, unified interface to models
that can be used to try a range of models without getting bogged down in
the syntactical minutiae of the underlying packages.

## Installation

``` r

# The easiest way to get parsnip is to install all of tidymodels:
install.packages("tidymodels")

# Alternatively, install just parsnip:
install.packages("parsnip")

# Or the development version from GitHub:
# install.packages("pak")
pak::pak("tidymodels/parsnip")
```

## Getting started

One challenge with different modeling functions available in R *that do
the same thing* is that they can have different interfaces and
arguments. For example, to fit a random forest regression model, we
might have:

``` r

# From randomForest
rf_1 <- randomForest(
  y ~ ., 
  data = dat, 
  mtry = 10, 
  ntree = 2000, 
  importance = TRUE
)

# From ranger
rf_2 <- ranger(
  y ~ ., 
  data = dat, 
  mtry = 10, 
  num.trees = 2000, 
  importance = "impurity"
)

# From sparklyr
rf_3 <- ml_random_forest(
  dat, 
  intercept = FALSE, 
  response = "y", 
  features = names(dat)[names(dat) != "y"], 
  col.sample.rate = 10,
  num.trees = 2000
)
```

Note that the model syntax can be very different and that the argument
names (and formats) are also different. This is a pain if you switch
between implementations.

In this example:

- the **type** of model is “random forest”,
- the **mode** of the model is “regression” (as opposed to
  classification, etc), and
- the computational **engine** is the name of the R package.

The goals of parsnip are to:

- Separate the definition of a model from its evaluation.
- Decouple the model specification from the implementation (whether the
  implementation is in R, spark, or something else). For example, the
  user would call `rand_forest` instead of
  [`ranger::ranger`](http://imbs-hl.github.io/ranger/reference/ranger.md)
  or other specific packages.
- Harmonize argument names (e.g. `n.trees`, `ntrees`, `trees`) so that
  users only need to remember a single name. This will help *across*
  model types too so that `trees` will be the same argument across
  random forest as well as boosting or bagging.

Using the example above, the parsnip approach would be:

``` r

library(parsnip)

rand_forest(mtry = 10, trees = 2000) |>
  set_engine("ranger", importance = "impurity") |>
  set_mode("regression")
#> Random Forest Model Specification (regression)
#> 
#> Main Arguments:
#>   mtry = 10
#>   trees = 2000
#> 
#> Engine-Specific Arguments:
#>   importance = impurity
#> 
#> Computational engine: ranger
```

The engine can be easily changed. To use Spark, the change is
straightforward:

``` r

rand_forest(mtry = 10, trees = 2000) |>
  set_engine("spark") |>
  set_mode("regression")
#> Random Forest Model Specification (regression)
#> 
#> Main Arguments:
#>   mtry = 10
#>   trees = 2000
#> 
#> Computational engine: spark
```

Either one of these model specifications can be fit in the same way:

``` r

set.seed(192)
rand_forest(mtry = 10, trees = 2000) |>
  set_engine("ranger", importance = "impurity") |>
  set_mode("regression") |>
  fit(mpg ~ ., data = mtcars)
#> parsnip model object
#> 
#> Ranger result
#> 
#> Call:
#>  ranger::ranger(x = maybe_data_frame(x), y = y, mtry = min_cols(~10,      x), num.trees = ~2000, importance = ~"impurity", num.threads = 1,      verbose = FALSE, seed = sample.int(10^5, 1)) 
#> 
#> Type:                             Regression 
#> Number of trees:                  2000 
#> Sample size:                      32 
#> Number of independent variables:  10 
#> Mtry:                             10 
#> Target node size:                 5 
#> Variable importance mode:         impurity 
#> Splitrule:                        variance 
#> OOB prediction error (MSE):       5.976917 
#> R squared (OOB):                  0.8354559
```

A list of all parsnip models across different CRAN packages can be found
at <https://www.tidymodels.org/find/parsnip/>.

## Contributing

This project is released with a [Contributor Code of
Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.

- For questions and discussions about tidymodels packages, modeling, and
  machine learning, please [post on RStudio
  Community](https://forum.posit.co/new-topic?category_id=15&tags=tidymodels,question).

- If you think you have encountered a bug, please [submit an
  issue](https://github.com/tidymodels/parsnip/issues).

- Either way, learn how to create and share a
  [reprex](https://reprex.tidyverse.org/articles/articles/learn-reprex.html)
  (a minimal, reproducible example), to clearly communicate about your
  code.

- Check out further details on [contributing guidelines for tidymodels
  packages](https://www.tidymodels.org/contribute/) and [how to get
  help](https://www.tidymodels.org/help/).

# Package index

## Models

- [`auto_ml()`](https://parsnip.tidymodels.org/reference/auto_ml.md) :
  Automatic Machine Learning
- [`bag_mars()`](https://parsnip.tidymodels.org/reference/bag_mars.md) :
  Ensembles of MARS models
- [`bag_mlp()`](https://parsnip.tidymodels.org/reference/bag_mlp.md) :
  Ensembles of neural networks
- [`bag_tree()`](https://parsnip.tidymodels.org/reference/bag_tree.md) :
  Ensembles of decision trees
- [`bart()`](https://parsnip.tidymodels.org/reference/bart.md) :
  Bayesian additive regression trees (BART)
- [`boost_tree()`](https://parsnip.tidymodels.org/reference/boost_tree.md)
  : Boosted trees
- [`cubist_rules()`](https://parsnip.tidymodels.org/reference/cubist_rules.md)
  : Cubist rule-based regression models
- [`C5_rules()`](https://parsnip.tidymodels.org/reference/C5_rules.md) :
  C5.0 rule-based classification models
- [`decision_tree()`](https://parsnip.tidymodels.org/reference/decision_tree.md)
  : Decision trees
- [`discrim_flexible()`](https://parsnip.tidymodels.org/reference/discrim_flexible.md)
  : Flexible discriminant analysis
- [`discrim_linear()`](https://parsnip.tidymodels.org/reference/discrim_linear.md)
  : Linear discriminant analysis
- [`discrim_quad()`](https://parsnip.tidymodels.org/reference/discrim_quad.md)
  : Quadratic discriminant analysis
- [`discrim_regularized()`](https://parsnip.tidymodels.org/reference/discrim_regularized.md)
  : Regularized discriminant analysis
- [`gen_additive_mod()`](https://parsnip.tidymodels.org/reference/gen_additive_mod.md)
  : Generalized additive models (GAMs)
- [`glm_grouped()`](https://parsnip.tidymodels.org/reference/glm_grouped.md)
  : Fit a grouped binomial outcome from a data set with case weights
- [`linear_reg()`](https://parsnip.tidymodels.org/reference/linear_reg.md)
  : Linear regression
- [`logistic_reg()`](https://parsnip.tidymodels.org/reference/logistic_reg.md)
  : Logistic regression
- [`mars()`](https://parsnip.tidymodels.org/reference/mars.md) :
  Multivariate adaptive regression splines (MARS)
- [`mlp()`](https://parsnip.tidymodels.org/reference/mlp.md) : Single
  layer neural network
- [`multinom_reg()`](https://parsnip.tidymodels.org/reference/multinom_reg.md)
  : Multinomial regression
- [`naive_Bayes()`](https://parsnip.tidymodels.org/reference/naive_Bayes.md)
  : Naive Bayes models
- [`nearest_neighbor()`](https://parsnip.tidymodels.org/reference/nearest_neighbor.md)
  : K-nearest neighbors
- [`null_model()`](https://parsnip.tidymodels.org/reference/null_model.md)
  : Null model
- [`ordinal_reg()`](https://parsnip.tidymodels.org/reference/ordinal_reg.md)
  : Ordinal regression
- [`pls()`](https://parsnip.tidymodels.org/reference/pls.md) : Partial
  least squares (PLS)
- [`poisson_reg()`](https://parsnip.tidymodels.org/reference/poisson_reg.md)
  : Poisson regression models
- [`proportional_hazards()`](https://parsnip.tidymodels.org/reference/proportional_hazards.md)
  : Proportional hazards regression
- [`rand_forest()`](https://parsnip.tidymodels.org/reference/rand_forest.md)
  : Random forest
- [`rule_fit()`](https://parsnip.tidymodels.org/reference/rule_fit.md) :
  RuleFit models
- [`survival_reg()`](https://parsnip.tidymodels.org/reference/survival_reg.md)
  : Parametric survival regression
- [`svm_linear()`](https://parsnip.tidymodels.org/reference/svm_linear.md)
  : Linear support vector machines
- [`svm_poly()`](https://parsnip.tidymodels.org/reference/svm_poly.md) :
  Polynomial support vector machines
- [`svm_rbf()`](https://parsnip.tidymodels.org/reference/svm_rbf.md) :
  Radial basis function support vector machines

## Infrastructure

- [`autoplot(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/autoplot.model_fit.md)
  [`autoplot(`*`<glmnet>`*`)`](https://parsnip.tidymodels.org/reference/autoplot.model_fit.md)
  : Create a ggplot for a model object
- [`add_rowindex()`](https://parsnip.tidymodels.org/reference/add_rowindex.md)
  : Add a column of row numbers to a data frame
- [`augment(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/augment.md)
  : Augment data with predictions
- [`case_weights`](https://parsnip.tidymodels.org/reference/case_weights.md)
  : Using case weights with parsnip
- [`case_weights_allowed()`](https://parsnip.tidymodels.org/reference/case_weights_allowed.md)
  : Determine if case weights are used
- [`.cols()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.preds()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.obs()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.lvls()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.facts()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.x()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.y()`](https://parsnip.tidymodels.org/reference/descriptors.md)
  [`.dat()`](https://parsnip.tidymodels.org/reference/descriptors.md) :
  Data Set Characteristics Available when Fitting Models
- [`extract_spec_parsnip(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/extract-parsnip.md)
  [`extract_fit_engine(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/extract-parsnip.md)
  [`extract_parameter_set_dials(`*`<model_spec>`*`)`](https://parsnip.tidymodels.org/reference/extract-parsnip.md)
  [`extract_parameter_dials(`*`<model_spec>`*`)`](https://parsnip.tidymodels.org/reference/extract-parsnip.md)
  [`extract_fit_time(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/extract-parsnip.md)
  : Extract elements of a parsnip model object
- [`fit(`*`<model_spec>`*`)`](https://parsnip.tidymodels.org/reference/fit.md)
  [`fit_xy(`*`<model_spec>`*`)`](https://parsnip.tidymodels.org/reference/fit.md)
  : Fit a Model Specification to a Dataset
- [`reexports`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`autoplot`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`%>%`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`fit`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`fit_xy`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`tidy`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`glance`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`augment`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`required_pkgs`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`contr_one_hot`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_spec_parsnip`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_fit_engine`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_parameter_set_dials`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_parameter_dials`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`tune`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`frequency_weights`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`importance_weights`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_fit_time`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`varying_args`](https://parsnip.tidymodels.org/reference/reexports.md)
  : Objects exported from other packages
- [`control_parsnip()`](https://parsnip.tidymodels.org/reference/control_parsnip.md)
  : Control the fit function
- [`glance(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/glance.model_fit.md)
  : Construct a single row summary "glance" of a model, fit, or other
  object
- [`matrix_to_quantile_pred()`](https://parsnip.tidymodels.org/reference/matrix_to_quantile_pred.md)
  : Reformat quantile predictions
- [`model_fit`](https://parsnip.tidymodels.org/reference/model_fit.md) :
  Model Fit Objects
- [`model_formula`](https://parsnip.tidymodels.org/reference/model_formula.md)
  : Formulas with special terms in tidymodels
- [`model_spec`](https://parsnip.tidymodels.org/reference/model_spec.md)
  : Model Specifications
- [`multi_predict()`](https://parsnip.tidymodels.org/reference/multi_predict.md)
  : Model predictions across many sub-models
- [`parsnip_addin()`](https://parsnip.tidymodels.org/reference/parsnip_addin.md)
  : Start an RStudio Addin that can write model specifications
- [`predict(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/predict.model_fit.md)
  [`predict_raw()`](https://parsnip.tidymodels.org/reference/predict.model_fit.md)
  : Model predictions
- [`repair_call()`](https://parsnip.tidymodels.org/reference/repair_call.md)
  : Repair a model call object
- [`set_args()`](https://parsnip.tidymodels.org/reference/set_args.md)
  [`set_mode()`](https://parsnip.tidymodels.org/reference/set_args.md) :
  Change elements of a model specification
- [`set_engine()`](https://parsnip.tidymodels.org/reference/set_engine.md)
  : Declare a computational engine and specific arguments
- [`show_engines()`](https://parsnip.tidymodels.org/reference/show_engines.md)
  : Display currently available engines for a model
- [`sparse_data`](https://parsnip.tidymodels.org/reference/sparse_data.md)
  : Using sparse data with parsnip
- [`tidy(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/tidy.model_fit.md)
  : Turn a parsnip model object into a tidy tibble
- [`translate()`](https://parsnip.tidymodels.org/reference/translate.md)
  : Resolve a Model Specification for a Computational Engine
- [`update(`*`<bag_mars>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<bag_mlp>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<bag_tree>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<bart>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<boost_tree>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<C5_rules>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<cubist_rules>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<decision_tree>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<discrim_flexible>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<discrim_linear>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<discrim_quad>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<discrim_regularized>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<gen_additive_mod>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<linear_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<logistic_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<mars>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<mlp>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<multinom_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<naive_Bayes>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<nearest_neighbor>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<ordinal_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<pls>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<poisson_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<proportional_hazards>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<rand_forest>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<rule_fit>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<surv_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<survival_reg>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<svm_linear>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<svm_poly>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  [`update(`*`<svm_rbf>`*`)`](https://parsnip.tidymodels.org/reference/parsnip_update.md)
  : Updating a model specification
- [`ctree_train()`](https://parsnip.tidymodels.org/reference/ctree_train.md)
  [`cforest_train()`](https://parsnip.tidymodels.org/reference/ctree_train.md)
  : A wrapper function for conditional inference tree models

## Developer tools

- [`condense_control()`](https://parsnip.tidymodels.org/reference/condense_control.md)
  : Condense control object into strictly smaller control object

- [`reexports`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`autoplot`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`%>%`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`fit`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`fit_xy`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`tidy`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`glance`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`augment`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`required_pkgs`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`contr_one_hot`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_spec_parsnip`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_fit_engine`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_parameter_set_dials`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_parameter_dials`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`tune`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`frequency_weights`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`importance_weights`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`extract_fit_time`](https://parsnip.tidymodels.org/reference/reexports.md)
  [`varying_args`](https://parsnip.tidymodels.org/reference/reexports.md)
  : Objects exported from other packages

- [`set_new_model()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_model_mode()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_model_engine()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_model_arg()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_dependency()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`get_dependency()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_fit()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`get_fit()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_pred()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`get_pred_type()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`show_model_info()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`pred_value_template()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`set_encoding()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  [`get_encoding()`](https://parsnip.tidymodels.org/reference/set_new_model.md)
  : Tools to Register Models

- [`maybe_matrix()`](https://parsnip.tidymodels.org/reference/maybe_matrix.md)
  [`maybe_data_frame()`](https://parsnip.tidymodels.org/reference/maybe_matrix.md)
  : Fuzzy conversions

- [`min_cols()`](https://parsnip.tidymodels.org/reference/min_cols.md)
  [`min_rows()`](https://parsnip.tidymodels.org/reference/min_cols.md) :
  Execution-time data dimension checks

- [`max_mtry_formula()`](https://parsnip.tidymodels.org/reference/max_mtry_formula.md)
  :

  Determine largest value of mtry from formula. This function
  potentially caps the value of `mtry` based on a formula and data set.
  This is a safe approach for survival and/or multivariate models.

- [`required_pkgs(`*`<model_spec>`*`)`](https://parsnip.tidymodels.org/reference/required_pkgs.model_spec.md)
  [`required_pkgs(`*`<model_fit>`*`)`](https://parsnip.tidymodels.org/reference/required_pkgs.model_spec.md)
  : Determine required packages for a model

- [`req_pkgs()`](https://parsnip.tidymodels.org/reference/req_pkgs.md)
  **\[deprecated\]** : Determine required packages for a model

- [`.extract_surv_status`](https://parsnip.tidymodels.org/reference/dot-extract_surv_status.md)
  : Extract survival status

- [`.extract_surv_time`](https://parsnip.tidymodels.org/reference/dot-extract_surv_time.md)
  : Extract survival time

- [`.model_param_name_key()`](https://parsnip.tidymodels.org/reference/dot-model_param_name_key.md)
  : Translate names of model tuning parameters

- [`.get_prediction_column_names()`](https://parsnip.tidymodels.org/reference/dot-get_prediction_column_names.md)
  : Obtain names of prediction columns for a fitted model or workflow

# Articles

### All vignettes

- [Dev
  checklists](https://parsnip.tidymodels.org/articles/checklists.md):

- [Introduction to
  parsnip](https://parsnip.tidymodels.org/articles/parsnip.md):

  The goal of parsnip is to provide a tidy, unified interface to models
  to avoid getting bogged down in the syntactical minutiae of the
  underlying software.

- [Evaluating submodels with the same model
  object](https://parsnip.tidymodels.org/articles/Submodels.md):

  You can use
  [`multi_predict()`](https://parsnip.tidymodels.org/reference/multi_predict.md)
  to evaluate submodels with the same model object and avoid having to
  fit any of the submodels.