Skip to contents

Create AST computation steps for survey variables

Source: R/steps.R
step_compute.Rd

CORE AST SYSTEM: This function now uses Abstract Syntax Tree (AST) evaluation as its fundamental engine. All computations are parsed into AST form, optimized, and evaluated with advanced dependency detection and error prevention.

Usage

step_compute(
  svy = NULL,
  ...,
  .by = NULL,
  use_copy = use_copy_default(),
  comment = "AST Compute step",
  .level = "auto",
  optimize_ast = TRUE,
  cache_ast = TRUE,
  validate_deps = TRUE
)

Arguments

svy

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

...

Computation expressions that are automatically parsed as AST. Each expression is converted to Abstract Syntax Tree for optimized evaluation. Names are assigned using new_var = expression

.by

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

use_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 "AST Compute step"

.level

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

optimize_ast

Whether to apply AST optimizations (constant folding, expression simplification). Default: TRUE

cache_ast

Whether to cache compiled AST expressions for reuse. Default: TRUE

validate_deps

Whether to validate all variable dependencies exist before execution. Default: TRUE

Value

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

Details

AST CORE ENGINE FEATURES:

1. Automatic AST Parsing:

  • All expressions converted to Abstract Syntax Trees

  • Static analysis performed before execution

  • Dependency detection prevents runtime errors

2. AST Optimization:

  • Constant expressions pre-calculated

  • Dead code elimination

  • Expression simplification

  • Optimized evaluation paths

3. Enhanced Error Prevention:

  • Missing variables detected before execution

  • Type checking when possible

  • Precise error locations with context

  • Dependency graphs for debugging

4. Performance Benefits:

  • Optimized evaluation reduces computation time

  • Cached AST compilation for repeated operations

  • Minimal overhead with significant gains

For RotativePanelSurvey objects, AST validation ensures computations are compatible with the specified hierarchical level:

  • "implantation": Household/dwelling level computations

  • "follow_up": Individual/person level computations

  • "quarter": Quarterly aggregated computations

  • "month": Monthly aggregated computations

  • "auto": AST automatically detects appropriate level

See also

step_recode for categorical recodings bake_steps to execute all pending steps

Examples

if (FALSE) { # \dontrun{
# Basic AST computation (automatic optimization)
ech <- ech |>
  step_compute(
    unemployed = ifelse(POBPCOAC %in% 3:5, 1, 0),
    comment = "Unemployment indicator - AST optimized"
  )

# Grouped calculation
ech <- ech |>
  step_compute(
    mean_household_income = mean(ht11, na.rm = TRUE),
    .by = "numero",
    comment = "Mean income by household"
  )

# Rotative panel specifying level
panel <- panel |>
  step_compute(
    activity_rate = active_population / total_population * 100,
    .level = "quarter",
    comment = "Quarterly activity rate"
  )
} # }