Read a microdata file into R

Reads a Stata (.dta), SPSS (.sav, .zsav, .por) or Excel (.xlsx, .xls) file, or the data file inside a .zip archive, keeping its variable and value labels. Pass it a path or what knbs_download_finaccess() returns. When the file has a knbsdata provenance sidecar beside it, the result carries that provenance: knbs_metadata() says where it came from and knbs_cite() cites it.

Usage

knbs_read_microdata(x, file = NULL, ...)

Arguments

x

A path, or a download record from knbs_download_finaccess() holding one data file.

file

For an archive, the entry to read. Needed only when it holds more than one data file.

...

Passed to the reader: haven::read_dta(), haven::read_sav(), haven::read_por() or readxl::read_excel(). col_select reads only some variables of a large Stata or SPSS file, and n_max only its first rows.

Value

A tibble. With a provenance sidecar, a knbs_microdata tibble whose metadata records the source, the producers, the file's checksum and its terms.

Details

Stata and SPSS files are read with haven, which must be installed. Value labels arrive as haven::labelled() columns: haven::as_factor() turns them into factors and haven::zap_labels() drops them. Each column's question text is in its "label" attribute.

An archive is unpacked to a temporary directory, which is removed once the file is read. If it holds more than one data file, name the one to read with file.

A first variable name that begins with the remnant of a byte-order mark, an encoding slip that puts a stray character or two in front of a name such as interview__key, is repaired, and the repair is noted in the metadata.

See also

knbs_download_finaccess(), knbs_cite()

Examples

# Any Stata or SPSS file; labels survive the round trip
path <- tempfile(fileext = ".dta")
haven::write_dta(
  tibble::tibble(id = 1:3,
                 sex = haven::labelled(c(1, 2, 1), c(Male = 1, Female = 2))),
  path
)
knbs_read_microdata(path)
#> # A tibble: 3 × 2
#>      id sex       
#>   <dbl> <dbl+lbl> 
#> 1     1 1 [Male]  
#> 2     2 2 [Female]
#> 3     3 1 [Male]  
knbs_read_microdata(path, col_select = "sex")
#> # A tibble: 3 × 1
#>   sex       
#>   <dbl+lbl> 
#> 1 1 [Male]  
#> 2 2 [Female]
#> 3 1 [Male]  
if (FALSE) { # interactive()
# A FinAccess survey, downloaded, verified and read with its provenance
fa <- knbs_read_microdata(
  knbs_download_finaccess("mse2023-stata", file.path(tempdir(), "finaccess"))
)
knbs_cite(fa)
}