read_spss: Read SPSS survey files

In retroharmonize: Ex Post Survey Data Harmonization

Read SPSS survey files

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.

Usage

read_spss(
  file,
  user_na = TRUE,
  dataset_bibentry = NULL,
  id = NULL,
  doi = NULL,
  .name_repair = "unique"
)

Arguments

file	Path to an SPSS survey file.
user_na	Logical. Should user-defined missing values be imported? Defaults to 'TRUE'.
dataset_bibentry	Optional bibliographic metadata created with [dataset::dublincore()] or [dataset::datacite()].
id	Optional survey identifier. Defaults to the file name without extension.
doi	Optional DOI identifier.
.name_repair	Strategy for repairing invalid or duplicated column names. Passed to [haven::read_spss()].

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.

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"'

See Also

Other import functions: harmonize_survey_variables(), pull_survey(), read_csv(), read_dta(), read_rds(), read_surveys()

Examples

path <- system.file(
  "examples",
  "iris.sav",
  package = "haven"
)

survey_object <- read_spss(path)

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

retroharmonize documentation built on May 21, 2026, 9:06 a.m.