% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/harmonize_var_names.R
\name{harmonize_var_names}
\alias{harmonize_var_names}
\title{Harmonize variable names across surveys}
\usage{
harmonize_var_names(
  survey_list,
  metadata,
  old = "var_name_orig",
  new = "var_name_suggested",
  rowids = TRUE
)
}
\arguments{
\item{survey_list}{A list of survey objects, typically imported
with [read_surveys()].}

\item{metadata}{A metadata table containing harmonization rules.
Typically created with [metadata_create()] and combined across
surveys.}

\item{old}{Name of the column in `metadata` containing
the original variable names.}

\item{new}{Name of the column in `metadata` containing
the harmonized variable names.}

\item{rowids}{Logical. Should original `rowid` variables
be renamed to `"uniqid"`?}
}
\value{
A list of surveys with harmonized variable names.
}
\description{
`harmonize_var_names()` renames variables across multiple
surveys to a shared harmonized naming scheme.

The harmonization rules are defined in a metadata table,
typically created with [metadata_create()].
}
\details{
Harmonize variable names in a list of survey objects using
a metadata crosswalk table.


The function can also be used for survey subsetting workflows.
If `metadata` contains only a subset of variables for a survey,
only those variables are retained in the harmonized output.
}
\examples{
examples_dir <- system.file(
  "examples",
  package = "retroharmonize"
)

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

example_surveys <- read_surveys(
  file.path(examples_dir, survey_files)
)

metadata <- metadata_create(
  example_surveys
)

metadata$var_name_suggested <-
  label_normalize(metadata$var_name)

metadata$var_name_suggested[
  metadata$label_orig == "age_education"
] <- "age_education"

harmonized_surveys <- harmonize_var_names(
  survey_list = example_surveys,
  metadata = metadata
)

harmonized_surveys[[1]]

}
\seealso{
[metadata_create()],
[crosswalk()]

Other harmonization functions:
\code{\link[=collect_val_labels]{collect_val_labels()}},
\code{\link[=crosswalk_surveys]{crosswalk_surveys()}},
\code{\link[=harmonize_na_values]{harmonize_na_values()}},
\code{\link[=harmonize_survey_values]{harmonize_survey_values()}},
\code{\link[=harmonize_values]{harmonize_values()}},
\code{\link[=is.crosswalk_table]{is.crosswalk_table()}},
\code{\link[=label_normalize]{label_normalize()}}
}
\concept{harmonization functions}
