update_role() alters an existing role in the recipe or assigns an initial role to variables that do not yet have a declared role.

add_role() adds an additional role to variables that already have a role in the recipe. It does not overwrite old roles, as a single variable can have multiple roles.

remove_role() eliminates a single existing role in the recipe.

add_role(recipe, ..., new_role = "predictor", new_type = NULL)

update_role(recipe, ..., new_role = "predictor", old_role = NULL)

remove_role(recipe, ..., old_role)

Arguments

recipe

An existing recipe().

...

One or more selector functions to choose which variables are being assigned a role. See selections() for more details.

new_role

A character string for a single role.

new_type

A character string for specific type that the variable should be identified as. If left as NULL, the type is automatically identified as the first type you see for that variable in summary(recipe).

old_role

A character string for the specific role to update for the variables selected by .... update_role() accepts a NULL as long as the variables have only a single role.

Value

An updated recipe object.

Details

update_role() should be used when a variable doesn't currently have a role in the recipe, or to replace an old_role with a new_role. add_role() only adds additional roles to variables that already have roles and will throw an error when the current role is missing (i.e. NA).

When using add_role(), if a variable is selected that already has the new_role, a warning is emitted and that variable is skipped so no duplicate roles are added.

Adding or updating roles is a useful way to group certain variables that don't fall in the standard "predictor" bucket. You can perform a step on all of the variables that have a custom role with the selector has_role().

Examples

library(recipes) library(modeldata) data(biomass) # Using the formula method, roles are created for any outcomes and predictors: recipe(HHV ~ ., data = biomass) %>% summary()
#> # A tibble: 8 x 4 #> variable type role source #> <chr> <chr> <chr> <chr> #> 1 sample nominal predictor original #> 2 dataset nominal predictor original #> 3 carbon numeric predictor original #> 4 hydrogen numeric predictor original #> 5 oxygen numeric predictor original #> 6 nitrogen numeric predictor original #> 7 sulfur numeric predictor original #> 8 HHV numeric outcome original
# However `sample` and `dataset` aren't predictors. Since they already have # roles, `update_role()` can be used to make changes: recipe(HHV ~ ., data = biomass) %>% update_role(sample, new_role = "id variable") %>% update_role(dataset, new_role = "splitting variable") %>% summary()
#> # A tibble: 8 x 4 #> variable type role source #> <chr> <chr> <chr> <chr> #> 1 sample nominal id variable original #> 2 dataset nominal splitting variable original #> 3 carbon numeric predictor original #> 4 hydrogen numeric predictor original #> 5 oxygen numeric predictor original #> 6 nitrogen numeric predictor original #> 7 sulfur numeric predictor original #> 8 HHV numeric outcome original
# `update_role()` cannot set a role to NA, use `remove_role()` for that if (FALSE) { recipe(HHV ~ ., data = biomass) %>% update_role(sample, new_role = NA_character_) } # ------------------------------------------------------------------------------ # Variables can have more than one role. `add_role()` can be used # if the column already has at least one role: recipe(HHV ~ ., data = biomass) %>% add_role(carbon, sulfur, new_role = "something") %>% summary()
#> # A tibble: 10 x 4 #> variable type role source #> <chr> <chr> <chr> <chr> #> 1 sample nominal predictor original #> 2 dataset nominal predictor original #> 3 carbon numeric predictor original #> 4 carbon numeric something original #> 5 hydrogen numeric predictor original #> 6 oxygen numeric predictor original #> 7 nitrogen numeric predictor original #> 8 sulfur numeric predictor original #> 9 sulfur numeric something original #> 10 HHV numeric outcome original
# `update_role()` has an argument called `old_role` that is required to # unambiguously update a role when the column currently has multiple roles. recipe(HHV ~ ., data = biomass) %>% add_role(carbon, new_role = "something") %>% update_role(carbon, new_role = "something else", old_role = "something") %>% summary()
#> # A tibble: 9 x 4 #> variable type role source #> <chr> <chr> <chr> <chr> #> 1 sample nominal predictor original #> 2 dataset nominal predictor original #> 3 carbon numeric predictor original #> 4 carbon numeric something else original #> 5 hydrogen numeric predictor original #> 6 oxygen numeric predictor original #> 7 nitrogen numeric predictor original #> 8 sulfur numeric predictor original #> 9 HHV numeric outcome original
# `carbon` has two roles at the end, so the last `update_roles()` fails since # `old_role` was not given. if (FALSE) { recipe(HHV ~ ., data = biomass) %>% add_role(carbon, sulfur, new_role = "something") %>% update_role(carbon, new_role = "something else") } # ------------------------------------------------------------------------------ # To remove a role, `remove_role()` can be used to remove a single role. recipe(HHV ~ ., data = biomass) %>% add_role(carbon, new_role = "something") %>% remove_role(carbon, old_role = "something") %>% summary()
#> # A tibble: 8 x 4 #> variable type role source #> <chr> <chr> <chr> <chr> #> 1 sample nominal predictor original #> 2 dataset nominal predictor original #> 3 carbon numeric predictor original #> 4 hydrogen numeric predictor original #> 5 oxygen numeric predictor original #> 6 nitrogen numeric predictor original #> 7 sulfur numeric predictor original #> 8 HHV numeric outcome original
# To remove all roles, call `remove_role()` multiple times to reset to `NA` recipe(HHV ~ ., data = biomass) %>% add_role(carbon, new_role = "something") %>% remove_role(carbon, old_role = "something") %>% remove_role(carbon, old_role = "predictor") %>% summary()
#> # A tibble: 8 x 4 #> variable type role source #> <chr> <chr> <chr> <chr> #> 1 sample nominal predictor original #> 2 dataset nominal predictor original #> 3 carbon numeric NA original #> 4 hydrogen numeric predictor original #> 5 oxygen numeric predictor original #> 6 nitrogen numeric predictor original #> 7 sulfur numeric predictor original #> 8 HHV numeric outcome original
# ------------------------------------------------------------------------------ # If the formula method is not used, all columns have a missing role: recipe(biomass) %>% summary()
#> # A tibble: 8 x 4 #> variable type role source #> <chr> <chr> <lgl> <chr> #> 1 sample nominal NA original #> 2 dataset nominal NA original #> 3 carbon numeric NA original #> 4 hydrogen numeric NA original #> 5 oxygen numeric NA original #> 6 nitrogen numeric NA original #> 7 sulfur numeric NA original #> 8 HHV numeric NA original