% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/import.R
\name{read_column_mapping}
\alias{read_column_mapping}
\title{Read a column mapping file}
\usage{
read_column_mapping(path, data = NULL)
}
\arguments{
\item{path}{Path to the filled mapping file (.xlsx or .csv).}

\item{data}{Optional data frame. If provided, the function validates that
every mapped column actually exists in the data.}
}
\value{
A named list where names are standard variable identifiers
(e.g. \code{"age"}, \code{"sbp1"}) and values are the corresponding
column names in the user's dataset.
Unmapped variables are set to \code{NULL}.
}
\description{
Reads a filled-in column mapping template (Excel or CSV) and returns a
named list suitable for passing to \code{\link[=clean_steps_data]{clean_steps_data()}}.  The mapping file
should have at least two columns: one with the standard variable name
(column A) and one with the user's column name (column C in the template,
or the third column).
}
\details{
This function is the manual alternative to \code{\link[=detect_steps_columns]{detect_steps_columns()}}.
Use it when your dataset has non-standard variable names that
auto-detection cannot resolve.

A blank template can be obtained from
\code{system.file("templates", "column_mapping_template.xlsx",
                   package = "stepssurvey")}
or downloaded from the Shiny app.

The function ignores domain-header rows (rows where column A is all-caps
with no entry in column C) and skips any row where the user's column name
is blank.
}
\examples{
\dontrun{
  cols <- read_column_mapping("my_mapping.xlsx")
  raw  <- import_steps_data("survey.dta")
  clean <- clean_steps_data(raw, cols)
}

}
