% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/merge_surveys.R
\name{merge_surveys}
\alias{merge_surveys}
\title{Merge and harmonize surveys}
\usage{
merge_surveys(survey_list, var_harmonization)
}
\arguments{
\item{survey_list}{A list of survey objects.}

\item{var_harmonization}{A metadata table describing the
  harmonization rules. The table must contain at least:

  - `filename`
  - `var_name_orig`
  - `var_name_target`
  - `var_label`}
}
\value{
A list of harmonized survey objects with standardized variable names
and variable labels.
}
\description{
`merge_surveys()` applies a harmonization specification to a list
of survey objects and returns harmonized survey datasets with
aligned variable names and metadata.
}
\details{
Harmonize variable names, labels, and identifiers across multiple
surveys using a metadata crosswalk table.


Prior to version 0.2.0 this function was called `merge_waves()`,
reflecting terminology commonly used in Eurobarometer surveys.

The harmonization table supplied in `var_harmonization`
typically originates from [metadata_create()] and contains
mappings between original and harmonized variable names.
}
\examples{
\donttest{

examples_dir <- system.file(
  "examples",
  package = "retroharmonize"
)

survey_files <- dir(
  examples_dir,
  pattern = "\\\\.rds$",
  full.names = TRUE
)

example_surveys <- read_surveys(
  survey_files
)

metadata <- metadata_create(
  survey_list = example_surveys
)

to_harmonize <- metadata \%>\%
  dplyr::filter(
    var_name_orig \%in\% c("rowid", "w1") |
      grepl("^trust", var_label_orig)
  ) \%>\%
  dplyr::mutate(
    var_label = var_label_normalize(var_label_orig),
    var_name_target = val_label_normalize(var_label),
    var_name_target = ifelse(
      .data$var_name_orig \%in\%
        c("rowid", "w1", "wex"),
      .data$var_name_orig,
      .data$var_name_target
    )
  )

merged_surveys <- merge_surveys(
  survey_list = example_surveys,
  var_harmonization = to_harmonize
)

merged_surveys[[1]]
}

}
\seealso{
[metadata_create()]

Other survey harmonization functions:
\code{\link[=merge_waves]{merge_waves()}}
}
\concept{survey harmonization functions}
