Partially update values using an explicit mapping

replace_values() replaces each value of x found in from with the corresponding value from to. Values not found in from retain their original value unchanged.

Use replace_values() when updating only specific values of an existing variable. When remapping the full range of values in x, recode_values() is a better choice.

replace_values() automatically inherits value labels and the variable label from x. Supply .label or .value_labels to override the inherited values.

When any of .label, .value_labels, or .description are supplied, or when x carries existing labels, output label metadata is written to @metadata after mutate(). When none apply, the output is the same type as x.

Usage

replace_values(
  x,
  ...,
  from = NULL,
  to = NULL,
  .label = NULL,
  .value_labels = NULL,
  .description = NULL
)

Arguments

x

Vector to partially update.

...

These dots are for future extensions and must be empty.

from

Vector of old values to replace. Must be the same type as x.

to

Vector of new values corresponding to from. Must be the same length as from.

.label

character(1) or NULL. Variable label stored in @metadata@variable_labels after mutate(). Overrides the label inherited from x.

.value_labels

Named vector or NULL. Value labels stored in @metadata@value_labels. Names are the label strings; values are the data values. Merged with any existing labels inherited from x; entries in .value_labels take precedence over inherited entries with the same name.

.description

character(1) or NULL. Plain-language description of how the variable was created. Stored in @metadata@transformations[[col]]$description after mutate().

Value

An updated version of x with the same type and size. If x carries labels or any surveytidy args are supplied, returns a haven_labelled vector; otherwise returns the same type as x.

See also

• dplyr::replace_values() for the base implementation.

• recode_values() for full value remapping with explicit from/to vectors; does not inherit labels from x automatically.

• replace_when() for condition-based partial replacement.

• na_if() to replace specific values with NA.

Other recoding: case_when(), if_else(), na_if(), recode_values(), replace_when()

Examples

library(surveycore)
library(surveytidy)

# create the survey design
ns_wave1_svy <- as_survey_nonprob(ns_wave1, weights = weight)

# basic replace_values — replace pid3 == 4 ("Something else") with 3
new <- ns_wave1_svy |>
  mutate(pid3_clean = replace_values(pid3, from = 4, to = 3)) |>
  select(pid3, pid3_clean)

new
#> 
#> ── Survey Design ───────────────────────────────────────────────────────────────
#> <survey_nonprob> (non-probability) [experimental]
#> Sample size: 6422
#> 
#> # A tibble: 6,422 × 2
#>     pid3 pid3_clean
#>    <dbl>      <dbl>
#>  1     1          1
#>  2     1          1
#>  3     1          1
#>  4     3          3
#>  5     2          2
#>  6     1          1
#>  7     4          3
#>  8     2          2
#>  9     2          2
#> 10     1          1
#> # ℹ 6,412 more rows
#> 
#> ℹ Design variables preserved but hidden: weight.
#> ℹ Use `print(x, full = TRUE)` to show all variables.

# value labels from pid3 carry over to pid3_clean automatically
new@metadata@value_labels
#> $pid3
#>       Democrat     Republican    Independent Something else 
#>              1              2              3              4 
#> 
#> $pid3_clean
#>    Democrat  Republican Independent 
#>           1           2           3 
#> 

# override the inherited variable label via .label
new <- ns_wave1_svy |>
  mutate(
    pid3_clean = replace_values(
      pid3,
      from = 4,
      to = 3,
      .label = "Party ID (3 categories)"
    )
  ) |>
  select(pid3, pid3_clean)

new@metadata@variable_labels
#> $pid3
#> [1] "3-category party ID"
#> 
#> $weight
#> [1] "Survey weight, continuous value from 0-5"
#> 
#> $pid3_clean
#> [1] "Party ID (3 categories)"
#> 

# provide updated value labels that reflect the recoded categories
new <- ns_wave1_svy |>
  mutate(
    pid3_clean = replace_values(
      pid3,
      from = 4,
      to = 3,
      .label = "Party ID (3 categories)",
      .value_labels = c(
        "Democrat" = 1,
        "Republican" = 2,
        "Independent/Other" = 3
      )
    )
  ) |>
  select(pid3, pid3_clean)

new@metadata@value_labels
#> $pid3
#>       Democrat     Republican    Independent Something else 
#>              1              2              3              4 
#> 
#> $pid3_clean
#>          Democrat        Republican Independent/Other 
#>                 1                 2                 3 
#> 

# attach a plain-language description of the transformation
new <- ns_wave1_svy |>
  mutate(
    pid3_clean = replace_values(
      pid3,
      from = 4,
      to = 3,
      .label = "Party ID (3 categories)",
      .description = paste(
        "'Something else' (pid3 == 4) replaced with",
        "value 3 (Independent)."
      )
    )
  ) |>
  select(pid3, pid3_clean)

new@metadata@transformations
#> $pid3_clean
#> $pid3_clean$fn
#> [1] "replace_values"
#> 
#> $pid3_clean$source_cols
#> [1] "pid3"
#> 
#> $pid3_clean$expr
#> [1] "replace_values(pid3, from = 4, to = 3, .label = \"Party ID (3 categories)\", "
#> [2] "    .description = paste(\"'Something else' (pid3 == 4) replaced with\", "    
#> [3] "        \"value 3 (Independent).\"))"                                         
#> 
#> $pid3_clean$output_type
#> [1] "vector"
#> 
#> $pid3_clean$description
#> [1] "'Something else' (pid3 == 4) replaced with value 3 (Independent)."
#> 
#>