tidymodels Skill
R machine learning with the tidymodels ecosystem. Covers recipes for preprocessing
(normalization, dummy encoding, imputation, interactions), parsnip for model
specifications (linear_reg, logistic_reg, rand_forest, boost_tree,
nearest_neighbor), workflows for combining recipe + model into a single fit/predict
pipeline, tune for hyperparameter optimization via grid search and cross-validation,
rsample for resampling (v-fold CV, bootstrap, LOO), and yardstick for evaluation
metrics (rmse, accuracy, roc_auc, confusion matrix). Engines: ranger (random
forest), glmnet (lasso/ridge/elasticnet), xgboost (gradient boosting), kknn
(k-nearest neighbors). Also covers model interpretation (permutation importance,
PDP/ICE, SHAP via DALEX, iml, and kernelshap) and fairness assessment
(fairmodels). UMAP via uwot (not part of tidymodels). Use when execution
language is R and the task involves classification, prediction, clustering via
recipes, or preprocessing for ML. Python equivalent: scikit-learn. For econometric
regression (OLS, FE, IV, DiD) use fixest or r-stats.
Comprehensive skill for machine learning in R with tidymodels. Covers supervised
methods (classification, regression), preprocessing (recipes), hyperparameter
tuning, resampling, evaluation, and unsupervised dimension reduction. Use decision
trees below to find the right guidance, then load detailed references.
What is tidymodels?
tidymodels (Kuhn & Wickham) is R's unified machine learning framework, designed
as the successor to caret:
- Recipe/workflow paradigm: Preprocessing (recipe) and model (parsnip spec)
are separate objects combined into a workflow -- different from scikit-learn's
Pipeline where steps are positional
- Engine abstraction:
set_engine() decouples model type from implementation
(e.g., rand_forest() |> set_engine("ranger") vs set_engine("randomForest"))
- Tidy evaluation: Results come back as tibbles, not custom S3/S4 objects
- Consistent interface: Every model uses
fit(), predict(), augment() --
same verbs regardless of engine
- Resampling first: Cross-validation and bootstrap are built into the tuning
workflow, not bolted on
Version Notes
This skill targets tidymodels 1.4.1 (R 4.5.3). Key package versions:
| Package |
Version |
Role |
| recipes |
1.3.2 |
Preprocessing step definitions |
| parsnip |
1.5.0 |
Model specifications + engine bindings |
| workflows |
1.3.0 |
Recipe + model bundling |
| tune |
2.0.1 |
Hyperparameter tuning infrastructure |
| rsample |
1.3.2 |
Resampling (CV, bootstrap, etc.) |
| yardstick |
1.4.0 |
Evaluation metrics |
| dials |
1.4.3 |
Parameter ranges for tuning |
| ranger |
0.18.0 |
Random forest engine |
| glmnet |
4.1-10 |
Regularized regression engine |
| xgboost |
3.2.1.1 |
Gradient boosting engine |
| kknn |
1.4.1 |
K-nearest neighbors engine |
| uwot |
0.2.4 |
UMAP (not tidymodels, standalone) |
| vip |
0.4.5 |
Variable importance plots |
| DALEX |
2.5.3 |
Model interpretation framework |
| iml |
0.11.4 |
Model interpretation framework |
| kernelshap |
0.9.1 |
Kernel SHAP |
| fairmodels |
1.2.2 |
Fairness assessment |
How to Use This Skill
Reference File Structure
Each topic in ./references/ contains focused documentation:
| File |
Purpose |
When to Read |
quickstart.md |
Full tidymodels workflow: recipe, model spec, workflow, fit, predict |
First use of tidymodels |
recipes.md |
step_normalize, step_dummy, step_impute_*, step_interact, roles |
Preprocessing tasks |
models.md |
parsnip model specs: linear_reg, logistic_reg, rand_forest, boost_tree, nearest_neighbor |
Choosing and configuring models |
workflows.md |
workflow() + add_recipe + add_model, fit(), predict(), augment() |
Building ML pipelines |
tuning.md |
tune(), tune_grid(), collect_metrics(), select_best(), finalize_workflow |
Hyperparameter optimization |
resampling.md |
vfold_cv, bootstraps, loo_cv, group_vfold_cv, strata, assessment/analysis |
Creating resamples |
engines.md |
ranger, glmnet, xgboost, kknn: engine-specific args, installation, tuning params |
Engine configuration |
unsupervised.md |
PCA via recipes::step_pca, UMAP via uwot::umap(), k-means via stats::kmeans |
Dimension reduction, clustering |
evaluation.md |
yardstick metrics: rmse, accuracy, roc_auc, conf_mat, metric_set() |
Evaluating model performance |
interpretation.md |
Permutation importance, PDP/ICE, SHAP via DALEX/iml/kernelshap, vip, native engine importance |
Explaining model predictions |
fairness.md |
fairness_check() via fairmodels + DALEX, yardstick group metrics, reweight/roc_pivot mitigation |
Fairness assessment of classifiers |
gotchas.md |
Recipe baking order, data leakage, parsnip mode, engine args, tidymodels vs caret |
Debugging common mistakes |
Reading Order
- New to tidymodels? Start with
quickstart.md then workflows.md
- Need preprocessing? Read
recipes.md
- Choosing a model? Read
models.md then engines.md
- Need tuning? Read
tuning.md then resampling.md
- Evaluating results? Read
evaluation.md
- Explaining predictions or feature importance? Read
interpretation.md
- Fairness assessment? Read
fairness.md
- Unsupervised task? Read
unsupervised.md
- Coming from scikit-learn? Read
quickstart.md then gotchas.md
- Having issues? Check
gotchas.md first
Related Skills
| Skill |
Relationship |
scikit-learn |
Python equivalent -- Pipeline/estimator pattern vs tidymodels recipe/workflow pattern. Load when execution language is Python. |
data-scientist |
Methodology guidance -- load for "when and why" behind methods |
r-python-translation |
Cross-language mappings for R tidymodels vs Python scikit-learn |
fixest |
Econometric regression with FE/IV/DiD in R. Use instead of tidymodels for causal inference. |
r-stats |
Base R stats for OLS/GLM without FE. Use instead of tidymodels for simple regression without regularization or tuning. |
ggplot2 |
Visualization of model results. tidymodels objects are tidy -- pipe directly to ggplot2. |
Routing guidance:
- For econometric regression (hypothesis testing, standard errors, coefficient
interpretation), use
fixest or r-stats -- not tidymodels
- For unsupervised methodology (when to cluster, how to validate), read
exploratory-unsupervised.md in the data-scientist skill
- For simple OLS/GLM without tuning or regularization, use
r-stats
- For data manipulation, use
tidyverse
Quick Decision Trees
"I need to build a predictive model"
What kind of prediction?
+-- Continuous outcome (regression)
| +-- Simple linear --> linear_reg() (./references/models.md)
| +-- Regularized (lasso/ridge) --> linear_reg(penalty, mixture) with glmnet
| | (./references/models.md + ./references/engines.md)
| +-- Tree-based --> rand_forest() or boost_tree()
| | (./references/models.md)
| +-- Need to tune hyperparameters --> ./references/tuning.md
| +-- NOTE: For econometric regression (causal inference, SEs),
| use fixest or r-stats instead
+-- Categorical outcome (classification)
| +-- Binary --> logistic_reg() (./references/models.md)
| +-- Multi-class --> multinom_reg() or rand_forest()
| | (./references/models.md; logistic_reg() is binary-only)
| +-- Best performance --> boost_tree() with xgboost
| | (./references/models.md + ./references/engines.md)
| +-- Need tuning --> ./references/tuning.md
"I need to preprocess data"
What preprocessing?
+-- Normalize numeric features --> step_normalize() (./references/recipes.md)
+-- Create dummy variables --> step_dummy() (./references/recipes.md)
+-- Handle missing values --> step_impute_mean/median/knn (./references/recipes.md)
+-- Create interactions --> step_interact() (./references/recipes.md)
+-- PCA / dimension reduction --> step_pca() (./references/unsupervised.md)
+-- Mixed types (numeric + categorical) --> recipe with multiple steps
| (./references/recipes.md)
+-- Feature engineering --> step_mutate(), step_log() (./references/recipes.md)
"I need to evaluate a model"
What evaluation?
+-- Regression metrics
| +-- RMSE, MAE, R-squared --> ./references/evaluation.md
+-- Classification metrics
| +-- Accuracy, ROC-AUC, confusion matrix --> ./references/evaluation.md
| +-- Precision, recall, F1 --> ./references/evaluation.md
+-- Cross-validated performance
| +-- collect_metrics() from tune_grid --> ./references/tuning.md
+-- Compare multiple models
| +-- collect_metrics() + bind_rows --> ./references/evaluation.md
"I need to interpret a model or assess fairness"
What do I need?
+-- Feature importance (permutation, model-agnostic) --> DALEX model_parts()
| or iml FeatureImp (./references/interpretation.md)
+-- Feature importance (engine-native, fast) --> ranger/xgboost importance + vip
| (./references/interpretation.md; ranger needs importance= in set_engine)
+-- Feature effects (PDP / ICE) --> DALEX model_profile() or iml FeatureEffect
| (./references/interpretation.md)
+-- SHAP values --> kernelshap (many rows) or predict_parts/Shapley (single row)
| (./references/interpretation.md)
+-- Fairness metrics by protected group --> fairmodels fairness_check()
| (./references/fairness.md)
+-- NOTE: methodology (when to interpret, causal caveats, fairness criteria)
--> data-scientist skill: supervised-ml.md
"I need to tune hyperparameters"
Tuning approach?
+-- Grid search (exhaustive) --> tune_grid() (./references/tuning.md)
+-- Which parameters to tune --> tune() placeholder + dials ranges
| (./references/tuning.md)
+-- Select best model --> select_best() + finalize_workflow()
| (./references/tuning.md)
+-- Resampling for tuning --> vfold_cv() (./references/resampling.md)
"I need unsupervised analysis"
What unsupervised method?
+-- PCA (within a recipe) --> step_pca() (./references/unsupervised.md)
+-- UMAP --> uwot::umap() (./references/unsupervised.md)
+-- K-means clustering --> stats::kmeans() (./references/unsupervised.md)
+-- NOTE: tidymodels focuses on supervised learning. For advanced
clustering, see data-scientist skill methodology guidance.
"Something isn't working"
Common issues?
+-- "recipe must be prepped" --> ./references/gotchas.md
+-- "set mode" error --> ./references/gotchas.md
+-- Engine-specific args not working --> ./references/gotchas.md
+-- Predictions wrong type --> ./references/gotchas.md
+-- Data leakage concerns --> ./references/gotchas.md
+-- tidymodels vs caret migration --> ./references/gotchas.md
File-First Execution in Research Workflows
Important: In DAAF research pipelines, tidymodels analyses are executed through
script files, not interactively. This ensures auditability and reproducibility.
The pattern:
- Write ML code to
scripts/stage8_analysis/{step}_{task-name}.R
- Execute via Bash with automatic output capture wrapper script
- Validation results get automatically embedded in scripts as comments
- If failed, create versioned copy for fixes
Closely read agent_reference/SCRIPT_EXECUTION_REFERENCE.md for the mandatory
file-first execution protocol covering complete code file writing, output capture,
and file versioning rules. All ML scripts must follow the Inline Audit Trail (IAT)
standard -- see agent_reference/INLINE_AUDIT_TRAIL.md. For ML code, document
model selection rationale (why this algorithm, why these hyperparameters, what
assumptions) with # INTENT:, # REASONING:, and # ASSUMES: comments.
See:
agent_reference/WORKFLOW_PHASE4_ANALYSIS.md -- Stage 8 (Analysis & Visualization)
agent_reference/INLINE_AUDIT_TRAIL.md -- IAT documentation standard
The examples below show tidymodels syntax. In research workflows, wrap them in
scripts following the file-first pattern.
Quick Reference
Essential Setup
library(tidymodels) # Loads recipes, parsnip, workflows, tune, rsample, yardstick, dials
library(arrow) # For parquet I/O (DAAF convention)
The tidymodels Workflow (5 Steps)
# 1. Define recipe (preprocessing)
rec <- recipe(outcome ~ ., data = train_data) |>
step_normalize(all_numeric_predictors()) |>
step_dummy(all_nominal_predictors())
# 2. Define model specification
spec <- rand_forest(trees = 500) |>
set_engine("ranger") |>
set_mode("classification")
# 3. Bundle into workflow
wf <- workflow() |>
add_recipe(rec) |>
add_model(spec)
# 4. Fit
fit <- wf |> fit(data = train_data)
# 5. Predict
preds <- fit |> predict(new_data = test_data)
Common Operations
| Operation |
Code |
| Create recipe |
recipe(y ~ ., data = df) |
| Normalize numeric |
step_normalize(all_numeric_predictors()) |
| Dummy encode |
step_dummy(all_nominal_predictors()) |
| Impute missing |
step_impute_median(all_numeric_predictors()) |
| Random forest |
rand_forest(trees = 500) |> set_engine("ranger") |
| Logistic regression |
logistic_reg() |> set_engine("glm") |
| Lasso |
linear_reg(penalty = 0.01, mixture = 1) |> set_engine("glmnet") |
| Ridge |
linear_reg(penalty = 0.01, mixture = 0) |> set_engine("glmnet") |
| XGBoost |
boost_tree(trees = 500) |> set_engine("xgboost") |
| Build workflow |
workflow() |> add_recipe(rec) |> add_model(spec) |
| Fit workflow |
wf |> fit(data = train_data) |
| Predict |
fit |> predict(new_data = test_data) |
| Augment |
fit |> augment(new_data = test_data) |
| V-fold CV |
vfold_cv(train_data, v = 10, strata = outcome) |
| Tune grid |
tune_grid(wf, resamples = folds, grid = 20) |
| Best params |
select_best(tune_results, metric = "rmse") |
| Finalize |
finalize_workflow(wf, best_params) |
| RMSE |
rmse(results, truth = y, estimate = .pred) |
| Accuracy |
accuracy(results, truth = y, estimate = .pred_class) |
| ROC AUC |
roc_auc(results, truth = y, .pred_class1) |
| Confusion matrix |
conf_mat(results, truth = y, estimate = .pred_class) |
Topic Index
| Topic |
Reference File |
| First tidymodels workflow |
./references/quickstart.md |
| recipe + spec + workflow pattern |
./references/quickstart.md |
| fit() and predict() |
./references/quickstart.md |
| train/test split |
./references/quickstart.md |
| step_normalize |
./references/recipes.md |
| step_dummy |
./references/recipes.md |
| step_impute_mean / median / knn |
./references/recipes.md |
| step_interact |
./references/recipes.md |
| step_mutate / step_log |
./references/recipes.md |
| Role assignment (update_role) |
./references/recipes.md |
| prep() and bake() |
./references/recipes.md |
| Selector functions |
./references/recipes.md |
| linear_reg |
./references/models.md |
| logistic_reg |
./references/models.md |
| multinom_reg (multiclass) |
./references/models.md |
| rand_forest |
./references/models.md |
| boost_tree |
./references/models.md |
| nearest_neighbor |
./references/models.md |
| set_engine() |
./references/models.md |
| set_mode() |
./references/models.md |
| workflow() construction |
./references/workflows.md |
| add_recipe / add_model |
./references/workflows.md |
| fit() on workflow |
./references/workflows.md |
| predict() on workflow |
./references/workflows.md |
| augment() |
./references/workflows.md |
| extract_fit_parsnip |
./references/workflows.md |
| tune() placeholder |
./references/tuning.md |
| tune_grid() |
./references/tuning.md |
| collect_metrics() |
./references/tuning.md |
| select_best() |
./references/tuning.md |
| finalize_workflow() |
./references/tuning.md |
| show_best() |
./references/tuning.md |
| dials parameter ranges |
./references/tuning.md |
| grid_space_filling / grid types |
./references/tuning.md |
| Parallel tuning (future backend) |
./references/tuning.md |
| vfold_cv |
./references/resampling.md |
| bootstraps |
./references/resampling.md |
| loo_cv |
./references/resampling.md |
| group_vfold_cv |
./references/resampling.md |
| strata argument |
./references/resampling.md |
| analysis() / assessment() |
./references/resampling.md |
| initial_split / training / testing |
./references/resampling.md |
| initial_validation_split / validation_set |
./references/resampling.md |
| ranger (random forest) |
./references/engines.md |
| glmnet (lasso / ridge / elasticnet) |
./references/engines.md |
| xgboost (gradient boosting) |
./references/engines.md |
| kknn (k-nearest neighbors) |
./references/engines.md |
| Engine-specific arguments |
./references/engines.md |
| PCA via step_pca |
./references/unsupervised.md |
| UMAP via uwot |
./references/unsupervised.md |
| K-means via stats::kmeans |
./references/unsupervised.md |
| rmse, mae, rsq |
./references/evaluation.md |
| accuracy, precision, recall, f_meas |
./references/evaluation.md |
| roc_auc, roc_curve |
./references/evaluation.md |
| conf_mat |
./references/evaluation.md |
| metric_set() |
./references/evaluation.md |
| Permutation importance (DALEX / iml) |
./references/interpretation.md |
| PDP / ICE plots |
./references/interpretation.md |
| SHAP (kernelshap, predict_parts, Shapley) |
./references/interpretation.md |
| vip / engine-native importance |
./references/interpretation.md |
| fairness_check (fairmodels) |
./references/fairness.md |
| Group-wise yardstick metrics |
./references/fairness.md |
| Fairness mitigation (reweight, roc_pivot) |
./references/fairness.md |
| Recipe baking order |
./references/gotchas.md |
| Data leakage in recipes |
./references/gotchas.md |
| parsnip mode requirement |
./references/gotchas.md |
| Engine-specific args (set_engine) |
./references/gotchas.md |
| tidymodels vs caret |
./references/gotchas.md |
| Prediction type (.pred vs .pred_class) |
./references/gotchas.md |
Citation
When this framework is used as a primary analytical tool, include in the report's
Software & Tools references:
Kuhn, M. & Wickham, H. (2020). Tidymodels: a collection of packages for
modeling and machine learning using tidyverse principles.
https://www.tidymodels.org
Cite when: tidymodels is used for model fitting, preprocessing, tuning, or
evaluation central to the analysis.
Do not cite when: Only loaded but no modeling performed.
For engine-specific citations:
Wright, M.N. & Ziegler, A. (2017). "ranger: A Fast Implementation of Random
Forests for High Dimensional Data in C++ and R." Journal of Statistical
Software, 77(1), 1-17. (ranger engine)
Friedman, J., Hastie, T., & Tibshirani, R. (2010). "Regularization Paths for
Generalized Linear Models via Coordinate Descent." Journal of Statistical
Software, 33(1), 1-22. (glmnet engine)
Chen, T. & Guestrin, C. (2016). "XGBoost: A Scalable Tree Boosting System."
Proceedings of the 22nd ACM SIGKDD, 785-794. (xgboost engine)
For method-specific citations, consult the reference files in this skill and
agent_reference/CITATION_REFERENCE.md.
1---2name: tidymodels3description: |4 R machine learning with tidymodels: recipes (preprocessing), parsnip5 (model specs), workflows (fit pipelines), tune (hyperparameters), rsample6 (resampling). Engines: ranger (RF), glmnet (lasso/ridge), xgboost, kknn.7 Model interpretation (permutation importance, PDP/ICE, SHAP via8 DALEX/iml/kernelshap) and fairness assessment (fairmodels). UMAP via uwot.9 Use when execution language is R. Python equivalent: scikit-learn.10 For econometric regression use fixest or r-stats.11autoload: never12metadata:13 source: https://skillmd.com/skills/majiayu000/tidymodels14 audience: research-coders15 domain: r-library16 library-version: "tidymodels 1.4.1"17 skill-last-updated: "2026-07-07"18 tags: ["r", "machine-learning", "tidymodels", "classification", "prediction"]19---2021# tidymodels Skill2223R machine learning with the tidymodels ecosystem. Covers recipes for preprocessing24(normalization, dummy encoding, imputation, interactions), parsnip for model25specifications (linear_reg, logistic_reg, rand_forest, boost_tree,26nearest_neighbor), workflows for combining recipe + model into a single fit/predict27pipeline, tune for hyperparameter optimization via grid search and cross-validation,28rsample for resampling (v-fold CV, bootstrap, LOO), and yardstick for evaluation29metrics (rmse, accuracy, roc_auc, confusion matrix). Engines: ranger (random30forest), glmnet (lasso/ridge/elasticnet), xgboost (gradient boosting), kknn31(k-nearest neighbors). Also covers model interpretation (permutation importance,32PDP/ICE, SHAP via DALEX, iml, and kernelshap) and fairness assessment33(fairmodels). UMAP via uwot (not part of tidymodels). Use when execution34language is R and the task involves classification, prediction, clustering via35recipes, or preprocessing for ML. Python equivalent: scikit-learn. For econometric36regression (OLS, FE, IV, DiD) use fixest or r-stats.3738Comprehensive skill for machine learning in R with tidymodels. Covers supervised39methods (classification, regression), preprocessing (recipes), hyperparameter40tuning, resampling, evaluation, and unsupervised dimension reduction. Use decision41trees below to find the right guidance, then load detailed references.4243## What is tidymodels?4445tidymodels (Kuhn & Wickham) is R's unified machine learning framework, designed46as the successor to caret:4748- **Recipe/workflow paradigm**: Preprocessing (recipe) and model (parsnip spec)49 are separate objects combined into a workflow -- different from scikit-learn's50 Pipeline where steps are positional51- **Engine abstraction**: `set_engine()` decouples model type from implementation52 (e.g., `rand_forest() |> set_engine("ranger")` vs `set_engine("randomForest")`)53- **Tidy evaluation**: Results come back as tibbles, not custom S3/S4 objects54- **Consistent interface**: Every model uses `fit()`, `predict()`, `augment()` --55 same verbs regardless of engine56- **Resampling first**: Cross-validation and bootstrap are built into the tuning57 workflow, not bolted on5859## Version Notes6061This skill targets **tidymodels 1.4.1** (R 4.5.3). Key package versions:6263| Package | Version | Role |64|---------|---------|------|65| recipes | 1.3.2 | Preprocessing step definitions |66| parsnip | 1.5.0 | Model specifications + engine bindings |67| workflows | 1.3.0 | Recipe + model bundling |68| tune | 2.0.1 | Hyperparameter tuning infrastructure |69| rsample | 1.3.2 | Resampling (CV, bootstrap, etc.) |70| yardstick | 1.4.0 | Evaluation metrics |71| dials | 1.4.3 | Parameter ranges for tuning |72| ranger | 0.18.0 | Random forest engine |73| glmnet | 4.1-10 | Regularized regression engine |74| xgboost | 3.2.1.1 | Gradient boosting engine |75| kknn | 1.4.1 | K-nearest neighbors engine |76| uwot | 0.2.4 | UMAP (not tidymodels, standalone) |77| vip | 0.4.5 | Variable importance plots |78| DALEX | 2.5.3 | Model interpretation framework |79| iml | 0.11.4 | Model interpretation framework |80| kernelshap | 0.9.1 | Kernel SHAP |81| fairmodels | 1.2.2 | Fairness assessment |8283## How to Use This Skill8485### Reference File Structure8687Each topic in `./references/` contains focused documentation:8889| File | Purpose | When to Read |90|------|---------|--------------|91| `quickstart.md` | Full tidymodels workflow: recipe, model spec, workflow, fit, predict | First use of tidymodels |92| `recipes.md` | step_normalize, step_dummy, step_impute_*, step_interact, roles | Preprocessing tasks |93| `models.md` | parsnip model specs: linear_reg, logistic_reg, rand_forest, boost_tree, nearest_neighbor | Choosing and configuring models |94| `workflows.md` | workflow() + add_recipe + add_model, fit(), predict(), augment() | Building ML pipelines |95| `tuning.md` | tune(), tune_grid(), collect_metrics(), select_best(), finalize_workflow | Hyperparameter optimization |96| `resampling.md` | vfold_cv, bootstraps, loo_cv, group_vfold_cv, strata, assessment/analysis | Creating resamples |97| `engines.md` | ranger, glmnet, xgboost, kknn: engine-specific args, installation, tuning params | Engine configuration |98| `unsupervised.md` | PCA via recipes::step_pca, UMAP via uwot::umap(), k-means via stats::kmeans | Dimension reduction, clustering |99| `evaluation.md` | yardstick metrics: rmse, accuracy, roc_auc, conf_mat, metric_set() | Evaluating model performance |100| `interpretation.md` | Permutation importance, PDP/ICE, SHAP via DALEX/iml/kernelshap, vip, native engine importance | Explaining model predictions |101| `fairness.md` | fairness_check() via fairmodels + DALEX, yardstick group metrics, reweight/roc_pivot mitigation | Fairness assessment of classifiers |102| `gotchas.md` | Recipe baking order, data leakage, parsnip mode, engine args, tidymodels vs caret | Debugging common mistakes |103104### Reading Order1051061. **New to tidymodels?** Start with `quickstart.md` then `workflows.md`1072. **Need preprocessing?** Read `recipes.md`1083. **Choosing a model?** Read `models.md` then `engines.md`1094. **Need tuning?** Read `tuning.md` then `resampling.md`1105. **Evaluating results?** Read `evaluation.md`1116. **Explaining predictions or feature importance?** Read `interpretation.md`1127. **Fairness assessment?** Read `fairness.md`1138. **Unsupervised task?** Read `unsupervised.md`1149. **Coming from scikit-learn?** Read `quickstart.md` then `gotchas.md`11510. **Having issues?** Check `gotchas.md` first116117## Related Skills118119| Skill | Relationship |120|-------|-------------|121| `scikit-learn` | Python equivalent -- Pipeline/estimator pattern vs tidymodels recipe/workflow pattern. Load when execution language is Python. |122| `data-scientist` | Methodology guidance -- load for "when and why" behind methods |123| `r-python-translation` | Cross-language mappings for R tidymodels vs Python scikit-learn |124| `fixest` | Econometric regression with FE/IV/DiD in R. Use instead of tidymodels for causal inference. |125| `r-stats` | Base R stats for OLS/GLM without FE. Use instead of tidymodels for simple regression without regularization or tuning. |126| `ggplot2` | Visualization of model results. tidymodels objects are tidy -- pipe directly to ggplot2. |127128**Routing guidance:**129- For econometric regression (hypothesis testing, standard errors, coefficient130 interpretation), use `fixest` or `r-stats` -- not tidymodels131- For unsupervised methodology (when to cluster, how to validate), read132 `exploratory-unsupervised.md` in the `data-scientist` skill133- For simple OLS/GLM without tuning or regularization, use `r-stats`134- For data manipulation, use `tidyverse`135136## Quick Decision Trees137138### "I need to build a predictive model"139140```141What kind of prediction?142+-- Continuous outcome (regression)143| +-- Simple linear --> linear_reg() (./references/models.md)144| +-- Regularized (lasso/ridge) --> linear_reg(penalty, mixture) with glmnet145| | (./references/models.md + ./references/engines.md)146| +-- Tree-based --> rand_forest() or boost_tree()147| | (./references/models.md)148| +-- Need to tune hyperparameters --> ./references/tuning.md149| +-- NOTE: For econometric regression (causal inference, SEs),150| use fixest or r-stats instead151+-- Categorical outcome (classification)152| +-- Binary --> logistic_reg() (./references/models.md)153| +-- Multi-class --> multinom_reg() or rand_forest()154| | (./references/models.md; logistic_reg() is binary-only)155| +-- Best performance --> boost_tree() with xgboost156| | (./references/models.md + ./references/engines.md)157| +-- Need tuning --> ./references/tuning.md158```159160### "I need to preprocess data"161162```163What preprocessing?164+-- Normalize numeric features --> step_normalize() (./references/recipes.md)165+-- Create dummy variables --> step_dummy() (./references/recipes.md)166+-- Handle missing values --> step_impute_mean/median/knn (./references/recipes.md)167+-- Create interactions --> step_interact() (./references/recipes.md)168+-- PCA / dimension reduction --> step_pca() (./references/unsupervised.md)169+-- Mixed types (numeric + categorical) --> recipe with multiple steps170| (./references/recipes.md)171+-- Feature engineering --> step_mutate(), step_log() (./references/recipes.md)172```173174### "I need to evaluate a model"175176```177What evaluation?178+-- Regression metrics179| +-- RMSE, MAE, R-squared --> ./references/evaluation.md180+-- Classification metrics181| +-- Accuracy, ROC-AUC, confusion matrix --> ./references/evaluation.md182| +-- Precision, recall, F1 --> ./references/evaluation.md183+-- Cross-validated performance184| +-- collect_metrics() from tune_grid --> ./references/tuning.md185+-- Compare multiple models186| +-- collect_metrics() + bind_rows --> ./references/evaluation.md187```188189### "I need to interpret a model or assess fairness"190191```192What do I need?193+-- Feature importance (permutation, model-agnostic) --> DALEX model_parts()194| or iml FeatureImp (./references/interpretation.md)195+-- Feature importance (engine-native, fast) --> ranger/xgboost importance + vip196| (./references/interpretation.md; ranger needs importance= in set_engine)197+-- Feature effects (PDP / ICE) --> DALEX model_profile() or iml FeatureEffect198| (./references/interpretation.md)199+-- SHAP values --> kernelshap (many rows) or predict_parts/Shapley (single row)200| (./references/interpretation.md)201+-- Fairness metrics by protected group --> fairmodels fairness_check()202| (./references/fairness.md)203+-- NOTE: methodology (when to interpret, causal caveats, fairness criteria)204 --> data-scientist skill: supervised-ml.md205```206207### "I need to tune hyperparameters"208209```210Tuning approach?211+-- Grid search (exhaustive) --> tune_grid() (./references/tuning.md)212+-- Which parameters to tune --> tune() placeholder + dials ranges213| (./references/tuning.md)214+-- Select best model --> select_best() + finalize_workflow()215| (./references/tuning.md)216+-- Resampling for tuning --> vfold_cv() (./references/resampling.md)217```218219### "I need unsupervised analysis"220221```222What unsupervised method?223+-- PCA (within a recipe) --> step_pca() (./references/unsupervised.md)224+-- UMAP --> uwot::umap() (./references/unsupervised.md)225+-- K-means clustering --> stats::kmeans() (./references/unsupervised.md)226+-- NOTE: tidymodels focuses on supervised learning. For advanced227 clustering, see data-scientist skill methodology guidance.228```229230### "Something isn't working"231232```233Common issues?234+-- "recipe must be prepped" --> ./references/gotchas.md235+-- "set mode" error --> ./references/gotchas.md236+-- Engine-specific args not working --> ./references/gotchas.md237+-- Predictions wrong type --> ./references/gotchas.md238+-- Data leakage concerns --> ./references/gotchas.md239+-- tidymodels vs caret migration --> ./references/gotchas.md240```241242## File-First Execution in Research Workflows243244**Important:** In DAAF research pipelines, tidymodels analyses are executed through245**script files**, not interactively. This ensures auditability and reproducibility.246247**The pattern:**2481. Write ML code to `scripts/stage8_analysis/{step}_{task-name}.R`2492. Execute via Bash with automatic output capture wrapper script2503. Validation results get automatically embedded in scripts as comments2514. If failed, create versioned copy for fixes252253Closely read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the mandatory254file-first execution protocol covering complete code file writing, output capture,255and file versioning rules. All ML scripts must follow the Inline Audit Trail (IAT)256standard -- see `agent_reference/INLINE_AUDIT_TRAIL.md`. For ML code, document257model selection rationale (why this algorithm, why these hyperparameters, what258assumptions) with `# INTENT:`, `# REASONING:`, and `# ASSUMES:` comments.259260**See:**261- `agent_reference/WORKFLOW_PHASE4_ANALYSIS.md` -- Stage 8 (Analysis & Visualization)262- `agent_reference/INLINE_AUDIT_TRAIL.md` -- IAT documentation standard263264The examples below show tidymodels syntax. In research workflows, wrap them in265scripts following the file-first pattern.266267---268269## Quick Reference270271### Essential Setup272273```r274library(tidymodels) # Loads recipes, parsnip, workflows, tune, rsample, yardstick, dials275library(arrow) # For parquet I/O (DAAF convention)276```277278### The tidymodels Workflow (5 Steps)279280```r281# 1. Define recipe (preprocessing)282rec <- recipe(outcome ~ ., data = train_data) |>283 step_normalize(all_numeric_predictors()) |>284 step_dummy(all_nominal_predictors())285286# 2. Define model specification287spec <- rand_forest(trees = 500) |>288 set_engine("ranger") |>289 set_mode("classification")290291# 3. Bundle into workflow292wf <- workflow() |>293 add_recipe(rec) |>294 add_model(spec)295296# 4. Fit297fit <- wf |> fit(data = train_data)298299# 5. Predict300preds <- fit |> predict(new_data = test_data)301```302303### Common Operations304305| Operation | Code |306|-----------|------|307| Create recipe | `recipe(y ~ ., data = df)` |308| Normalize numeric | `step_normalize(all_numeric_predictors())` |309| Dummy encode | `step_dummy(all_nominal_predictors())` |310| Impute missing | `step_impute_median(all_numeric_predictors())` |311| Random forest | `rand_forest(trees = 500) \|> set_engine("ranger")` |312| Logistic regression | `logistic_reg() \|> set_engine("glm")` |313| Lasso | `linear_reg(penalty = 0.01, mixture = 1) \|> set_engine("glmnet")` |314| Ridge | `linear_reg(penalty = 0.01, mixture = 0) \|> set_engine("glmnet")` |315| XGBoost | `boost_tree(trees = 500) \|> set_engine("xgboost")` |316| Build workflow | `workflow() \|> add_recipe(rec) \|> add_model(spec)` |317| Fit workflow | `wf \|> fit(data = train_data)` |318| Predict | `fit \|> predict(new_data = test_data)` |319| Augment | `fit \|> augment(new_data = test_data)` |320| V-fold CV | `vfold_cv(train_data, v = 10, strata = outcome)` |321| Tune grid | `tune_grid(wf, resamples = folds, grid = 20)` |322| Best params | `select_best(tune_results, metric = "rmse")` |323| Finalize | `finalize_workflow(wf, best_params)` |324| RMSE | `rmse(results, truth = y, estimate = .pred)` |325| Accuracy | `accuracy(results, truth = y, estimate = .pred_class)` |326| ROC AUC | `roc_auc(results, truth = y, .pred_class1)` |327| Confusion matrix | `conf_mat(results, truth = y, estimate = .pred_class)` |328329## Topic Index330331| Topic | Reference File |332|-------|---------------|333| First tidymodels workflow | `./references/quickstart.md` |334| recipe + spec + workflow pattern | `./references/quickstart.md` |335| fit() and predict() | `./references/quickstart.md` |336| train/test split | `./references/quickstart.md` |337| step_normalize | `./references/recipes.md` |338| step_dummy | `./references/recipes.md` |339| step_impute_mean / median / knn | `./references/recipes.md` |340| step_interact | `./references/recipes.md` |341| step_mutate / step_log | `./references/recipes.md` |342| Role assignment (update_role) | `./references/recipes.md` |343| prep() and bake() | `./references/recipes.md` |344| Selector functions | `./references/recipes.md` |345| linear_reg | `./references/models.md` |346| logistic_reg | `./references/models.md` |347| multinom_reg (multiclass) | `./references/models.md` |348| rand_forest | `./references/models.md` |349| boost_tree | `./references/models.md` |350| nearest_neighbor | `./references/models.md` |351| set_engine() | `./references/models.md` |352| set_mode() | `./references/models.md` |353| workflow() construction | `./references/workflows.md` |354| add_recipe / add_model | `./references/workflows.md` |355| fit() on workflow | `./references/workflows.md` |356| predict() on workflow | `./references/workflows.md` |357| augment() | `./references/workflows.md` |358| extract_fit_parsnip | `./references/workflows.md` |359| tune() placeholder | `./references/tuning.md` |360| tune_grid() | `./references/tuning.md` |361| collect_metrics() | `./references/tuning.md` |362| select_best() | `./references/tuning.md` |363| finalize_workflow() | `./references/tuning.md` |364| show_best() | `./references/tuning.md` |365| dials parameter ranges | `./references/tuning.md` |366| grid_space_filling / grid types | `./references/tuning.md` |367| Parallel tuning (future backend) | `./references/tuning.md` |368| vfold_cv | `./references/resampling.md` |369| bootstraps | `./references/resampling.md` |370| loo_cv | `./references/resampling.md` |371| group_vfold_cv | `./references/resampling.md` |372| strata argument | `./references/resampling.md` |373| analysis() / assessment() | `./references/resampling.md` |374| initial_split / training / testing | `./references/resampling.md` |375| initial_validation_split / validation_set | `./references/resampling.md` |376| ranger (random forest) | `./references/engines.md` |377| glmnet (lasso / ridge / elasticnet) | `./references/engines.md` |378| xgboost (gradient boosting) | `./references/engines.md` |379| kknn (k-nearest neighbors) | `./references/engines.md` |380| Engine-specific arguments | `./references/engines.md` |381| PCA via step_pca | `./references/unsupervised.md` |382| UMAP via uwot | `./references/unsupervised.md` |383| K-means via stats::kmeans | `./references/unsupervised.md` |384| rmse, mae, rsq | `./references/evaluation.md` |385| accuracy, precision, recall, f_meas | `./references/evaluation.md` |386| roc_auc, roc_curve | `./references/evaluation.md` |387| conf_mat | `./references/evaluation.md` |388| metric_set() | `./references/evaluation.md` |389| Permutation importance (DALEX / iml) | `./references/interpretation.md` |390| PDP / ICE plots | `./references/interpretation.md` |391| SHAP (kernelshap, predict_parts, Shapley) | `./references/interpretation.md` |392| vip / engine-native importance | `./references/interpretation.md` |393| fairness_check (fairmodels) | `./references/fairness.md` |394| Group-wise yardstick metrics | `./references/fairness.md` |395| Fairness mitigation (reweight, roc_pivot) | `./references/fairness.md` |396| Recipe baking order | `./references/gotchas.md` |397| Data leakage in recipes | `./references/gotchas.md` |398| parsnip mode requirement | `./references/gotchas.md` |399| Engine-specific args (set_engine) | `./references/gotchas.md` |400| tidymodels vs caret | `./references/gotchas.md` |401| Prediction type (.pred vs .pred_class) | `./references/gotchas.md` |402403## Citation404405When this framework is used as a primary analytical tool, include in the report's406Software & Tools references:407408> Kuhn, M. & Wickham, H. (2020). Tidymodels: a collection of packages for409> modeling and machine learning using tidyverse principles.410> https://www.tidymodels.org411412**Cite when:** tidymodels is used for model fitting, preprocessing, tuning, or413evaluation central to the analysis.414**Do not cite when:** Only loaded but no modeling performed.415416For engine-specific citations:417418> Wright, M.N. & Ziegler, A. (2017). "ranger: A Fast Implementation of Random419> Forests for High Dimensional Data in C++ and R." Journal of Statistical420> Software, 77(1), 1-17. (ranger engine)421422> Friedman, J., Hastie, T., & Tibshirani, R. (2010). "Regularization Paths for423> Generalized Linear Models via Coordinate Descent." Journal of Statistical424> Software, 33(1), 1-22. (glmnet engine)425426> Chen, T. & Guestrin, C. (2016). "XGBoost: A Scalable Tree Boosting System."427> Proceedings of the 22nd ACM SIGKDD, 785-794. (xgboost engine)428429For method-specific citations, consult the reference files in this skill and430`agent_reference/CITATION_REFERENCE.md`.