% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/read_spss.R
\name{read_spss}
\alias{read_spss}
\title{Read SPSS survey files}
\usage{
read_spss(
  file,
  user_na = TRUE,
  dataset_bibentry = NULL,
  id = NULL,
  doi = NULL,
  .name_repair = "unique"
)
}
\arguments{
\item{file}{Path to an SPSS survey file.}

\item{user_na}{Logical. Should user-defined missing values be imported?
Defaults to `TRUE`.}

\item{dataset_bibentry}{Optional bibliographic metadata created with
[dataset::dublincore()] or [dataset::datacite()].}

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

\item{doi}{Optional DOI identifier.}

\item{.name_repair}{Strategy for repairing invalid or duplicated
column names. Passed to [haven::read_spss()].}
}
\value{
A `survey` object inheriting from `data.frame` and `tbl_df`.

Variable labels are stored in the `"label"` attribute of each variable.

Additional provenance metadata are stored as attributes, including:

- `"id"`
- `"doi"`
- `"object_size"`
- `"source_file_size"`
}
\description{
Import SPSS survey files in `.sav`, `.zsav`, or `.por` format and
convert them into harmonized `survey` objects with preserved metadata,
labelled variables, and provenance information.
}
\details{
This function wraps [haven::read_spss()] and adds:

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


`read_sav()` reads both `.sav` and `.zsav` files.
`read_por()` reads portable SPSS `.por` files.
`read_spss()` automatically dispatches to the appropriate importer
based on file extension.

Variables that inherit from `haven_labelled` but do not contain
valid label definitions are converted to standard numeric or
character vectors.

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

survey_object <- read_spss(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_dta]{read_dta()}},
\code{\link[=read_rds]{read_rds()}},
\code{\link[=read_surveys]{read_surveys()}}
}
\concept{import functions}
