Skip to contents

Create computation steps for survey variables

Source: R/steps.R
step_compute.Rd

This function uses optimized expression evaluation with automatic dependency detection and error prevention. All computations are validated before execution.

Usage

step_compute(
  svy = NULL,
  ...,
  .by = NULL,
  .copy = use_copy_default(),
  comment = "Compute step",
  .level = "auto",
  use_copy = deprecated()
)

Arguments

svy

A Survey or RotativePanelSurvey object. If NULL, creates a step that can be applied later using the pipe operator (%>%)

...

Computation expressions with automatic optimization. Names are assigned using new_var = expression

.by

Vector of variables to group computations by. The system automatically validates these variables exist before execution

.copy

Logical indicating whether to create a copy of the object before applying transformations. Defaults to use_copy_default()

comment

Descriptive text for the step for documentation and traceability. Compatible with Markdown syntax. Defaults to "Compute step"

.level

For RotativePanelSurvey objects (default "auto"), specifies the level where computations are applied: "implantation", "follow_up", "quarter", "month", or "auto"

use_copy

[Deprecated] Use .copy instead.

Value

Same type of input object (Survey or RotativePanelSurvey) with new computed variables and the step added to the history

Details

Lazy evaluation (default): By default, steps are recorded but not executed until bake_steps() is called. This allows building a full pipeline before materializing any changes. Set options(metasurvey.lazy_processing = FALSE) to apply steps immediately.

Expression processing: Expressions are evaluated using data.table's := operator. Variable dependencies are detected automatically via all.vars(). Missing variables are caught before execution.

Grouped computations: Use .by to compute aggregated values (e.g., group means) that are automatically joined back to the data.

For RotativePanelSurvey objects, .level controls where computations are applied:

  • "auto" (default): applies to both implantation and follow-ups

  • "implantation": household/dwelling level only

  • "follow_up": individual/person level only

See also

step_recode for categorical recodings bake_steps to execute all pending steps

Other steps: bake_steps(), get_steps(), step_filter(), step_join(), step_recode(), step_remove(), step_rename(), step_validate(), view_graph()

Examples

# Basic computation
dt <- data.table::data.table(
  id = 1:5, age = c(25, 30, 45, 50, 60), w = 1
)
svy <- Survey$new(
  data = dt, edition = "2023", type = "test",
  psu = NULL, engine = "data.table", weight = add_weight(annual = "w")
)
svy <- svy |> step_compute(age_squared = age^2, comment = "Age squared")
svy <- bake_steps(svy)
get_data(svy)
#>       id   age     w age_squared
#>    <int> <num> <num>       <num>
#> 1:     1    25     1         625
#> 2:     2    30     1         900
#> 3:     3    45     1        2025
#> 4:     4    50     1        2500
#> 5:     5    60     1        3600

# \donttest{
# ECH example: labor indicator
# ech <- ech |>
#   step_compute(
#     unemployed = ifelse(POBPCOAC %in% 3:5, 1, 0),
#     comment = "Unemployment indicator")
# }