Skip to contents

Join external data into survey (step)

Source: R/steps.R
step_join.Rd

Creates a step that joins additional data into a Survey or RotativePanelSurvey. Works with a data.frame/data.table or another Survey as the right-hand side.

Usage

step_join(
  svy = survey_empty(),
  x,
  by = NULL,
  type = c("left", "inner", "right", "full"),
  suffixes = c("", ".y"),
  use_copy = use_copy_default(),
  comment = "Join step",
  lazy = lazy_default(),
  record = TRUE
)

Arguments

svy

A Survey or RotativePanelSurvey object. If NULL, returns a step call

x

A data.frame/data.table or a Survey to join into svy

by

Character vector of join keys. Named vector for different names between svy and x (names are keys in svy, values are keys in x). If NULL, tries to infer common column names

type

Join type: "left" (default), "inner", "right", or "full"

suffixes

Length-2 character vector of suffixes for conflicting columns from svy and x respectively. Defaults to c("", ".y")

use_copy

Whether to operate on a copy (default: use_copy_default())

comment

Optional description for the step

lazy

Logical, whether to delay execution.

record

Logical, whether to record the step.

Value

Modified survey object with the join recorded as a step (and applied immediately when baked). For RotativePanelSurvey, the join is applied to implantation and every follow_up survey.

Details

  • Supports left, inner, right, and full joins

  • Allows named by mapping (e.g., c("id" = "code")) or simple vector

  • Avoids extra dependencies; resolves name conflicts by suffixing RHS columns

Examples

if (FALSE) { # \dontrun{
# With data.frame
s <- Survey$new(
  data = data.table::data.table(id = 1:3, w = 1, a = c("x","y","z")),
  edition = "2023", type = "ech", psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w")
)
info <- data.frame(id = c(1,2), b = c(10,20))
s2 <- step_join(s, info, by = "id", type = "left")
s2 <- bake_steps(s2)

# With another Survey
s_right <- Survey$new(
  data = data.table::data.table(id = c(2,3), b = c(200, 300), w2 = 1),
  edition = "2023", type = "ech", psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w2")
)
s3 <- step_join(s, s_right, by = c("id" = "id"), type = "inner")
s3 <- bake_steps(s3)
} # }