add-recipe-step

name	add-recipe-step
description	Create a new preprocessing step for the recipes package following tidymodels conventions

Add Recipe Step

Guide for developing new preprocessing steps that extend the recipes package. This skill provides best practices, complete code templates, and testing patterns for creating custom recipe steps.

---

Two Development Contexts

This skill supports two distinct development contexts:

🆕 Extension Development (Default)

Creating a new R package that extends recipes with custom steps.

• ✅ Use this for: New packages, standalone steps, CRAN submissions

• ⚠️ Constraint: Must use recipes:: prefix for all functions

🔧 Source Development (Advanced)

Contributing directly to recipes via pull requests.

• ✅ Use this for: Contributing to tidymodels/recipes repository

• ✨ Benefit: Can use internal functions directly (no prefix needed)

---

Getting Started

INSTRUCTIONS FOR CLAUDE: Run the verification script first to determine the development context:

Rscript -e 'source(Sys.glob(path.expand("~/.claude/plugins/cache/tidymodels-skills/tidymodels-dev/*/tidymodels/shared-references/scripts/verify-setup.R"))[1])'

Then follow the appropriate path based on the output:

• Output: "All checks for source development complete." → Go to Source Development Guide

• Output: "All checks for extension development complete." (no warnings) → Go to Extension Development Guide

• Output: Shows "Warning - [UUID]" messages → Go to Extension Prerequisites to resolve warnings first

---

Implementation Workflow

INSTRUCTIONS FOR CLAUDE: Load references progressively based on step type.

Step 1: Read Step Type Reference ONLY

Determine step type from user requirements, then read ONLY that reference:

• Modifies existing columns? Read modify-in-place-steps.md ONLY

• Creates new columns? Read create-new-columns-steps.md ONLY

• Filters/removes rows? Read row-operation-steps.md ONLY

Do NOT read all three references. Read only the one needed for this step type.

Step 2: Read Additional References If Needed

Read other references ONLY if specifically mentioned or needed:

• User asks about helpers? Read helper-functions.md

• User mentions tunable? Read optional-methods.md

• Troubleshooting? Read troubleshooting references

Default: Don't pre-load optional references.

---

Overview

Creating a custom recipe step provides:

• Integration with the recipes preprocessing pipeline

• Automatic handling of variable selection and roles

• Support for case weights

• Consistent prep/bake workflow

• Integration with tune for hyperparameter optimization

• Proper handling of grouped data frames

• Sparse data support (when applicable)

Repository Access (Optional but Recommended)

INSTRUCTIONS FOR CLAUDE: Check if repos/recipes/ exists in the current working directory. Use this to guide development:

If repos/recipes/ exists:

• ✅ Use it as a reference throughout development

• Read source files (e.g., repos/recipes/R/center.R) to study implementation patterns

• Read test files (e.g., repos/recipes/tests/testthat/test-center.R) for testing patterns

• Reference these files when answering complex questions or solving problems

• Look at actual code structure, validation patterns, and edge case handling

If repos/recipes/ does NOT exist:

• Suggest cloning the repository using the scripts in Repository Access Guide

• This is optional but strongly recommended for high-quality development

• If the user declines, reference files using GitHub URLs:

  • Format: https://github.com/tidymodels/recipes/blob/main/R/[file-name].R

  • Example: https://github.com/tidymodels/recipes/blob/main/R/center.R

  • This allows users to click through to see implementations

When to use repository references:

• Complex implementation questions (e.g., "How does recipes handle variable roles?")

• Debugging issues (compare user's code to working implementation)

• Understanding patterns (study similar steps)

• Test design (see how recipes tests edge cases)

• Architecture decisions (understand internal structure)

See Repository Access Guide for setup instructions.

Quick Navigation

Development Guides:

• Extension Development Guide - Creating new packages that extend recipes

• Source Development Guide - Contributing PRs to recipes itself

Reference Files:

• Step Architecture - Three-function pattern, prep/bake workflow, step types

• Modify-in-Place Steps - Transform existing columns

• Create-New-Columns Steps - Generate new columns

• Row-Operation Steps - Filter or remove rows

• Optional Methods - tunable(), required_pkgs(), sparsity methods

• Helper Functions - recipes helper function reference

Shared References (Extension Development):

• Extension Prerequisites - Extension prerequisites

• Development Workflow - Fast iteration cycle

• Testing Patterns (Extension) - Extension testing guide

• Roxygen Documentation - Documentation templates

• Package Imports - Managing dependencies

• Best Practices (Extension) - Extension code style

• Troubleshooting (Extension) - Extension issues

Source Development Specific:

• Testing Patterns (Source) - Using internal helpers

• Best Practices (Source) - Using internal functions

• Troubleshooting (Source) - Source-specific issues

Development Workflow

See Development Workflow for complete details.

Fast iteration cycle (run repeatedly):

1. devtools::document() - Generate documentation
2. devtools::load_all() - Load your package
3. devtools::test() - Run tests

Final validation (run once at end):

4. devtools::check() - Full R CMD check

WARNING: Do NOT run check() during iteration. It takes 1-2 minutes and is unnecessary until you're done.

Understanding Recipe Steps

See Step Architecture for complete details.

The Three-Function Pattern

Every recipe step consists of three functions:

1. Step constructor (e.g., step_center()) - User-facing function

   • Captures user arguments

   • Uses enquos(...) to capture variable selections

   • Returns recipe with step added via add_step()

2. Step initialization (e.g., step_center_new()) - Internal constructor

   • Minimal function with no defaults

   • Calls step(subclass = "name", ...) to create S3 object

3. S3 methods - Required methods for every step:

   • prep.step_*() - Estimates parameters from training data

   • bake.step_*() - Applies transformation to new data

   • print.step_*() - Displays step in recipe summary

   • tidy.step_*() - Returns step information as tibble

The prep/bake Workflow

prep() - Training phase:

• Resolves variable selections (e.g., all_numeric() → actual column names)

• Validates column types

• Computes statistics/parameters from training data

• Stores learned parameters in step object

• Returns updated step with trained = TRUE

bake() - Application phase:

• Takes trained step and new data

• Validates required columns exist

• Applies transformation using stored parameters

• Returns transformed data

Example workflow:

# Define recipe with step
rec <- recipe(mpg ~ ., data = mtcars) |>
  step_center(all_numeric_predictors())

# prep() trains the step (calculates means)
trained_rec <- prep(rec, training = mtcars)

# bake() applies the step (subtracts means)
new_data <- bake(trained_rec, new_data = mtcars)

Step Type Decision Tree

Choose the appropriate template based on what your step does:

┌─────────────────────────────────────────────────────────────┐
│ What does your step do?                                    │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
        ▼                   ▼                   ▼
   Transform           Create new          Remove/filter
   existing            columns             rows
   columns
        │                   │                   │
        ▼                   ▼                   ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  MODIFY IN  │     │   CREATE    │     │     ROW     │
│    PLACE    │     │ NEW COLUMNS │     │  OPERATION  │
└─────────────┘     └─────────────┘     └─────────────┘
        │                   │                   │
        ▼                   ▼                   ▼
  role = NA           role =            skip = TRUE
  No keep_cols    "predictor"          (usually)
                  keep_original_cols
        │                   │                   │
        ▼                   ▼                   ▼
  Examples:           Examples:           Examples:

  - center            - dummy             - filter

  - scale             - pca               - sample

  - normalize         - interact          - naomit

  - log               - poly              - slice

Decision guide:

• Modify-in-place: Transforms existing columns → Modify-in-Place Steps

• Create new columns: Generates new columns from existing → Create-New-Columns Steps

• Row operations: Filters or removes rows → Row-Operation Steps

Complete Example: Modify-in-Place Step (Centering)

This example shows all required components for a modify-in-place step using extension development patterns (with recipes:: prefix).

For source development, see Source Development Guide for examples using internal functions directly.

Reference implementation: R/center.R in recipes repository

1. Step constructor

# R/center.R

#' Center numeric variables
#'
#' `step_center()` creates a *specification* of a recipe step that will
#' normalize numeric data to have a mean of zero.
#'
#' @inheritParams step_normalize
#' @param ... One or more selector functions to choose variables for this step.
#'   See [recipes::selections()] for more details.
#' @param role Not used by this step since no new variables are created.
#' @param na_rm A logical value indicating whether NA values should be removed
#'   when computing means.
#' @param means A named numeric vector of means. This is `NULL` until computed
#'   by [prep()].
#'
#' @return An updated version of `recipe` with the new step added to the
#'   sequence of any existing operations.
#'
#' @family normalization steps
#' @export
#'
#' @details
#' Centering data means that the average of the variable is subtracted from the
#' data. `step_center` estimates the variable means from the data used in the
#' `training` argument of [prep()]. [bake()] then applies the centering to new
#' data sets using these means.
#'
#' # Tidying
#'
#' When you [`tidy()`][recipes::tidy.recipe()] this step, a tibble is returned
















step_center  
  recipe
  ...
  role  
  trained  
  means  
  na_rm  
  skip  
  id  recipesrand_id
 
  recipesadd_step
    recipe
    step_center_new
      terms  rlangenquos...
      trained  trained
      role  role
      means  means
      na_rm  na_rm
      skip  skip
      id  id
      case_weights  
    
  


step_center_new  terms role trained means na_rm skip id
                            case_weights 
  recipesstep
    subclass  
    terms  terms
    role  role
    trained  trained
    means  means
    na_rm  na_rm
    skip  skip
    id  id
    case_weights  case_weights
  

2. prep() method

#' @export
prep.step_center <- function(x, training, info = NULL, ...) {
  # 1. Resolve variable selections to actual column names
  col_names <- recipes::recipes_eval_select(x$terms, training, info)

  # 2. Validate column types
  recipes::check_type(training[, col_names], types = c("double", "integer"))

  # 3. Extract case weights if applicable
  wts <- recipes::get_case_weights(info, training)
  were_weights_used <- recipes::are_weights_used(wts, unsupervised = TRUE)
  if (isFALSE(were_weights_used)) 
    wts  
  

  
  means  vapply
    training col_names
    col 
       wts 
        meancol na.rm  xna_rm
        
        weighted.meancol w  wts na.rm  xna_rm
      
    
    numeric
  

  
  inf_cols  col_namesmeans
   inf_cols   
    clicli_warn
      
    
  

  
  step_center_new
    terms  xterms
    role  xrole
    trained  
    means  means
    na_rm  xna_rm
    skip  xskip
    id  xid
    case_weights  were_weights_used
  

3. bake() method

#' @export
bake.step_center <- function(object, new_data, ...) {
  # 1. Get column names from trained step
  col_names <- names(object$means)

  # 2. Validate required columns exist in new data
  recipes::check_new_data(col_names, object, new_data)

  # 3. Apply transformation
  for (col_name in col_names) {
    new_data[[col_name]] <- new_data[[col_name]] - object$means[[col_name]]
  }

  # 4. Return modified data
  new_data
}

4. print() and tidy() methods

#' @export
print.step_center <- function(x, width = max(20, options()$width - 30), ...) {
  title <- "Centering for "
  recipes::print_step(
    x$columns,
    x$terms,
    x$trained,
    title,
    width,
    case_weights = x$case_weights
  )
  invisible(x)
}

#' @rdname tidy.recipe
#' @export
tidy.step_center <- function(x, ...) {
  if (recipes::is_trained(x)) {
    res  tibbletibble
      terms  xmeans
      value  unnamexmeans
    
    
    term_names  recipessel2charxterms
    res  tibbletibble
      terms  term_names
      value  rlangna_dbl
    
  
  resid  xid
  res

5. Tests

# tests/testthat/test-center.R

test_that("centering works correctly", {
  rec <- recipe(mpg ~ ., data = mtcars) |>
    step_center(disp, hp)

  prepped <- prep(rec, training = mtcars)
  results <- bake(prepped, mtcars)

  # Check means are approximately zero
  expect_equal(mean(results$disp), 0, tolerance = 1e-7)
  expect_equal(mean(results$hp), 0, tolerance = 1e-7)

  # Check tidy output
  trained_tidy <- tidy(prepped, 1)
  expect_equal(trained_tidy$value, meanmtcarsdisp meanmtcarshp


test_that 
  df  mtcars
  dfdisp  

  
  rec_remove  recipempg  . data  df 
    step_centerdisp na_rm  
  prepped  preprec_remove training  df
  results  bakeprepped df

  
  expect_trueresultsdisp
  expect_falseresultsdispnrowdf


test_that 
  df  data.frame
    x  
    y  
  

  rec  recipe . data  df 
    step_centery  

  expect_errorpreprec training  df


test_that 
  df  mtcars 
  dfweights       

  rec  recipempg  . data  df 
    step_centerdisp

  
  rec_unweighted  preprec training  df

  
  df_weighted  df
  df_weightedweights  hardhatimportance_weightsdf_weightedweights

  rec_weighted  recipempg  . data  df_weighted 
    update_roleweights new_role   
    step_centerdisp
  rec_weighted  preprec_weighted training  df_weighted

  
  expect_false
    tidyrec_unweighted value  tidyrec_weighted value
  

Reference test pattern: tests/testthat/test-center.R in recipes repository

See Testing Patterns for comprehensive testing guide.

Implementation Guide by Step Type

Modify-in-Place Steps

Use for: Transform existing columns without creating new ones.

Pattern: role = NA, no keep_original_cols parameter

Complete guide: Modify-in-Place Steps

Key points:

• Preserve existing column roles with role = NA

• Use recipes_eval_select() to resolve selections

• Validate with check_type() in prep()

• Apply transformation in place in bake()

Examples: center, scale, normalize, log

Reference implementations:

• Simple transformations: R/center.R, R/scale.R, R/normalize.R

• Math transformations: R/log.R, R/sqrt.R, R/logit.R

• With parameters: R/BoxCox.R (power transformation with lambda)

Create-New-Columns Steps

Use for: Generate new columns from existing ones.

Pattern: role = "predictor", keep_original_cols parameter

Complete guide: Create-New-Columns Steps

Key points:

• Assign role to new columns with role = "predictor"

• Include keep_original_cols parameter (default FALSE)

• Use remove_original_cols() helper in bake()

• Consider implementing .recipes_estimate_sparsity() for sparse columns

Examples: dummy, pca, interact, poly

Reference implementations:

• Encoding: R/dummy.R (one-hot encoding)

• Dimension reduction: R/pca.R, R/ica.R

• Feature engineering: R/interact.R, R/poly.R

Row-Operation Steps

Use for: Filter or remove rows from data.

Pattern: skip = TRUE by default

Complete guide: Row-Operation Steps

Key points:

• Default skip = TRUE since row ops usually only for training

• prep() typically doesn't learn parameters

• bake() applies filtering logic

• Respect skip parameter in bake()

Examples: filter, sample, naomit, slice

Reference implementations:

• Filtering: R/filter.R, R/filter_missing.R

• Sampling: R/sample.R

• Row removal: R/naomit.R, R/slice.R

Helper Functions

See Helper Functions for complete reference.

Essential helpers:

• recipes_eval_select() - Convert selections to column names (prep)

• check_type() - Validate column types (prep)

• check_new_data() - Verify columns exist (bake)

• get_case_weights() - Extract case weights (prep)

• are_weights_used() - Check if weights apply (prep)

• remove_original_cols() - Handle keep_original_cols (bake)

• print_step() - Standard printing (print)

• sel2char() - Convert selections to strings (tidy)

Optional Methods

See Optional Methods for complete details.

Optional S3 methods:

• tunable() - Declare parameters for tune package

• required_pkgs() - Declare external package dependencies

• .recipes_preserve_sparsity() - Indicate sparse preservation

• .recipes_estimate_sparsity() - Estimate sparsity of new columns

Documentation

See Roxygen Documentation for complete templates.

Required roxygen tags:

#' @inheritParams step_center
#' @param ... One or more selector functions
#' @param role Role for new variables (or NA)
#' @param trained Logical for training status
#' @param [params] Step-specific parameters
#' @return Updated recipe object
#' @family [category] steps
#' @export

Testing

See Testing Patterns (Extension) for comprehensive guide.

Required test categories: 1. Correctness: Step transforms data correctly 2. Variable selection: Works with all_numeric(), all_predictors(), etc. 3. NA handling: Both na_rm = TRUE and FALSE 4. Case weights: Weighted and unweighted differ 5. Infrastructure: Works in full recipe pipeline 6. Edge cases: Empty data, all same values, etc.

Package-Specific Patterns (Source Development)

If you're contributing to recipes itself, you have access to internal functions and conventions not available in extension development.

File Naming Conventions

Recipes organizes steps by category:

• Normalization: R/center.R, R/scale.R, R/normalize.R

• Encoding: R/dummy.R, R/novel.R, R/other.R

• Dimension reduction: R/pca.R, R/ica.R

• Row operations: R/filter.R, R/sample.R

• Tests: tests/testthat/test-center.R

Internal Functions Available

When developing recipes itself, you can use functions directly (no recipes:: prefix):

• recipes_eval_select() - Variable selection

• get_case_weights(), are_weights_used() - Case weight handling

• check_type() - Column type validation

• check_new_data() - Verify columns exist in new data

• remove_original_cols() - Handle keep_original_cols

• print_step() - Standard printing

• sel2char() - Convert selections to strings

Documentation Patterns

Recipes uses extensive parameter inheritance:

#' @inheritParams step_normalize
#' @template step-return
#' @template case-weights-unsupervised

The Three-Function Pattern (Source)

# 1. Constructor (exported)
step_center <- function(recipe, ..., role = NA, ...) {
  add_step(recipe, step_center_new(...))
}

# 2. Initialization (internal)
step_center_new <- function(terms, role, trained, ...) {
  step(subclass = "center", ...)
}

# 3. Methods (all exported)
prep.step_center <- function(x, training, info = NULL, ...) {
  # Use internal functions directly
  col_names <- recipes_eval_select(x$terms, training, info)
  check_type(training[, col_names] types   
  

Complete source development guide: Source Development Guide

---

Best Practices

See Best Practices for complete guide.

Key principles:

• Use base pipe |> not magrittr pipe %>%

• Prefer for-loops over purrr::map() for better error messages

• Use cli::cli_abort() for error messages

• Validate early (in prep), trust data in bake

• Use recipes helpers instead of reimplementing

Troubleshooting

See Troubleshooting (Extension) for complete guide.

Common issues:

• "No visible global function definition" → Add to package imports

• "Object not found" in tests → Use devtools::load_all() before testing

• Column selection not working → Check recipes_eval_select() usage

• Case weights ignored → Check conversion of hardhat weights

Related Skills

• add-yardstick-metric - Custom recipe steps may generate outputs that need custom metrics

• add-dials-parameter - Recipe steps often have tunable parameters that can be optimized

• add-parsnip-model - Preprocessed data flows into model specifications

• add-parsnip-engine - Recipe steps prepare data for model engines

Next Steps

For Extension Development (creating new packages):

1. Extension prerequisites: Extension Prerequisites - START HERE

For Source Development (contributing to recipes):

1. Start here: Source Development Guide
2. Clone repository: See Repository Access
3. Study existing steps: Browse R/center.R, R/dummy.R, R/pca.R, etc.
4. Follow package conventions: File naming, internal functions, three-function pattern
5. Test with internal helpers: See Testing Patterns (Source)
6. Submit PR: See Source Development Guide for PR process