% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_dta.R
\name{read_dta}
\alias{read_dta}
\title{Read a Stata `.dta` survey file}
\usage{
read_dta(file, id = NULL, doi = NULL, .name_repair = "unique")
}
\arguments{
\item{file}{Path to a Stata `.dta` file.}

\item{id}{Optional survey identifier. Defaults to the file name
without extension.}

\item{doi}{Optional DOI identifier for the survey.}

\item{.name_repair}{Strategy for repairing invalid or duplicated
column names. Passed to [haven::read_dta()].}
}
\value{
A `survey` object inheriting from `data.frame` and `tbl_df`.
}
\description{
Import a survey dataset stored in Stata `.dta` format and convert it
into a `survey` object with harmonized metadata and labelled variables.
}
\details{
This function wraps [haven::read_dta()] and adds:

- error handling,
- survey metadata creation,
- `rowid` normalization,
- preservation of variable labels,
- conversion of labelled variables,
- and provenance metadata.


Variable labels are preserved using the `"label"` attribute.

Labelled variables are converted to harmonized labelled survey vectors
where possible. Variables that inherit from `haven_labelled` but do not
contain valid label definitions are converted back to standard vectors.

If the file cannot be read, the function returns an empty `survey`
object and emits a warning.
}
\examples{
\donttest{
path <- system.file(
  "examples",
  "iris.dta",
  package = "haven"
)

survey_object <- read_dta(path)

attr(survey_object, "id")
attr(survey_object, "filename")
}

}
\seealso{
Other import functions:
\code{\link[=harmonize_survey_variables]{harmonize_survey_variables()}},
\code{\link[=pull_survey]{pull_survey()}},
\code{\link[=read_csv]{read_csv()}},
\code{\link[=read_rds]{read_rds()}},
\code{\link[=read_spss]{read_spss()}},
\code{\link[=read_surveys]{read_surveys()}}
}
\concept{import functions}
