Partially update a vector using conditional formulas

replace_when() is a survey-aware version of dplyr::replace_when() that evaluates each formula case sequentially and replaces matching elements of x with the corresponding RHS value. Elements where no case matches retain their original value from x.

Use replace_when() when partially updating an existing vector. When creating an entirely new vector from conditions, case_when() is a better choice.

replace_when() 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 identical to dplyr::replace_when().

Usage

replace_when(x, ..., .label = NULL, .value_labels = NULL, .description = NULL)

Arguments

x: A vector to partially update.
...: <dynamic-dots> A sequence of two-sided formulas (condition ~ value). The left-hand side must be a logical vector the same size as x. The right-hand side provides the replacement value, cast to the type of x. Cases are evaluated sequentially; the first matching case is used. NULL inputs are ignored.
.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.

Examples

library(surveycore)
library(surveytidy)

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

# basic replace_when — replace pid3 == 4 ("Something else") with 3
new <- ns_wave1_svy |>
  mutate(pid3_clean = replace_when(pid3, pid3 == 4 ~ 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_when(
      pid3,
      pid3 == 4 ~ 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 reflecting the collapsed categories
new <- ns_wave1_svy |>
  mutate(
    pid3_clean = replace_when(
      pid3,
      pid3 == 4 ~ 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_when(
      pid3,
      pid3 == 4 ~ 3,
      .label = "Party ID (3 categories)",
      .description = paste(
        "Recoded pid3: 'Something else' (4) merged into",
        "Independent (3)."
      )
    )
  ) |>
  select(pid3, pid3_clean)

new@metadata@transformations
#> $pid3_clean
#> $pid3_clean$fn
#> [1] "replace_when"
#> 
#> $pid3_clean$source_cols
#> [1] "pid3"
#> 
#> $pid3_clean$expr
#> [1] "replace_when(pid3, pid3 == 4 ~ 3, .label = \"Party ID (3 categories)\", "     
#> [2] "    .description = paste(\"Recoded pid3: 'Something else' (4) merged into\", "
#> [3] "        \"Independent (3).\"))"                                               
#> 
#> $pid3_clean$output_type
#> [1] "vector"
#> 
#> $pid3_clean$description
#> [1] "Recoded pid3: 'Something else' (4) merged into Independent (3)."
#> 
#>

Partially update a vector using conditional formulas

Usage

Arguments

Value

See also

Examples