Movatterモバイル変換

haven: Import and Export 'SPSS', 'Stata' and 'SAS' Files

Description

Import foreign statistical formats into R via the embedded 'ReadStat' C library,https://github.com/WizardMac/ReadStat.

Author(s)

Maintainer: Hadley Wickhamhadley@posit.co

Authors:

• Evan Miller (Author of included ReadStat code) [copyright holder]

• Danny Smith

Other contributors:

• Posit Software, PBC [copyright holder, funder]

See Also

Useful links:

• https://haven.tidyverse.org

• https://github.com/tidyverse/haven

• https://github.com/WizardMac/ReadStat

• Report bugs athttps://github.com/tidyverse/haven/issues

Convert labelled vectors to factors

Description

The base functionas.factor() is not a generic, butforcats::as_factor()is. haven providesas_factor() methods forlabelled() andlabelled_spss() vectors, and data frames. By default, when applied to adata frame, it only affects labelled columns.

Usage

## S3 method for class 'data.frame'as_factor(x, ..., only_labelled = TRUE)## S3 method for class 'haven_labelled'as_factor(  x,  levels = c("default", "labels", "values", "both"),  ordered = FALSE,  ...)## S3 method for class 'labelled'as_factor(  x,  levels = c("default", "labels", "values", "both"),  ordered = FALSE,  ...)

Arguments

Details

Includes methods for both classhaven_labelled andlabelledfor backward compatibility.

Examples

x <- labelled(sample(5, 10, replace = TRUE), c(Bad = 1, Good = 5))# Default method uses values where availableas_factor(x)# You can also extract just the labelsas_factor(x, levels = "labels")# Or just the valuesas_factor(x, levels = "values")# Or combine value and labelas_factor(x, levels = "both")# as_factor() will preserve SPSS missing values from values and rangesy <- labelled_spss(1:10, na_values = c(2, 4), na_range = c(8, 10))as_factor(y)# use zap_missing() first to convert to NAszap_missing(y)as_factor(zap_missing(y))

Create a labelled vector.

Description

A labelled vector is a common data structure in other statisticalenvironments, allowing you to assign text labels to specific values.This class makes it possible to import such labelled vectors in to Rwithout loss of fidelity. This class provides few methods, as Iexpect you'll coerce to a standard R class (e.g. afactor())soon after importing.

Usage

labelled(x = double(), labels = NULL, label = NULL)is.labelled(x)

Arguments

Examples

s1 <- labelled(c("M", "M", "F"), c(Male = "M", Female = "F"))s2 <- labelled(c(1, 1, 2), c(Male = 1, Female = 2))s3 <- labelled(  c(1, 1, 2),  c(Male = 1, Female = 2),  label = "Assigned sex at birth")# Unfortunately it's not possible to make as.factor work for labelled objects# so instead use as_factor. This works for all types of labelled vectors.as_factor(s1)as_factor(s1, levels = "values")as_factor(s2)# Other statistical software supports multiple types of missing valuess3 <- labelled(  c("M", "M", "F", "X", "N/A"),  c(Male = "M", Female = "F", Refused = "X", "Not applicable" = "N/A"))s3as_factor(s3)# Often when you have a partially labelled numeric vector, labelled values# are special types of missing. Use zap_labels to replace labels with missing# valuesx <- labelled(c(1, 2, 1, 2, 10, 9), c(Unknown = 9, Refused = 10))zap_labels(x)

Labelled vectors for SPSS

Description

This class is only used whenuser_na = TRUE inread_sav(). It is similar to thelabelled() classbut it also models SPSS's user-defined missings, which can be up tothree distinct values, or for numeric vectors a range.

Usage

labelled_spss(  x = double(),  labels = NULL,  na_values = NULL,  na_range = NULL,  label = NULL)

Arguments

Examples

x1 <- labelled_spss(1:10, c(Good = 1, Bad = 8), na_values = c(9, 10))is.na(x1)x2 <- labelled_spss(  1:10,  c(Good = 1, Bad = 8),  na_range = c(9, Inf),  label = "Quality rating")is.na(x2)# Print data and metadatax2

Print the labels of a labelled vector

Description

This is a convenience function, useful to explore the variables ofa newly imported dataset.

Usage

print_labels(x, name = NULL)

Arguments

Examples

s1 <- labelled(c("M", "M", "F"), c(Male = "M", Female = "F"))s2 <- labelled(c(1, 1, 2), c(Male = 1, Female = 2))labelled_df <- tibble::tibble(s1, s2)for (var in names(labelled_df)) {  print_labels(labelled_df[[var]], var)}

Read and write Stata DTA files

Description

Currently haven can read and write logical, integer, numeric, characterand factors. Seelabelled() for how labelled variables inStata are handled in R.

Character vectors will be stored asstrL if any components arestrl_threshold bytes or longer (andversion >= 13); otherwise they willbe stored as the appropriatestr#.

Usage

read_dta(  file,  encoding = NULL,  col_select = NULL,  skip = 0,  n_max = Inf,  .name_repair = "unique")read_stata(  file,  encoding = NULL,  col_select = NULL,  skip = 0,  n_max = Inf,  .name_repair = "unique")write_dta(  data,  path,  version = 14,  label = attr(data, "label"),  strl_threshold = 2045,  adjust_tz = TRUE)

Arguments

Value

A tibble, data frame variant with nice defaults.

Variable labels are stored in the "label" attribute of each variable.It is not printed on the console, but the RStudio viewer will show it.

If a dataset label is defined in Stata, it will stored in the "label"attribute of the tibble.

write_dta() returns the inputdata invisibly.

Character encoding

Prior to Stata 14, files did not declare a text encoding, and thedefault encoding differed across platforms. Ifencoding = NULL,haven assumes the encoding is windows-1252, the text encoding used byStata on Windows. Unfortunately Stata on Mac and Linux use a differentdefault encoding, "latin1". If you encounter an error such as"Unable to convert string to the requested encoding", tryencoding = "latin1"

For Stata 14 and later, you should not need to manually specifyencodingvalue unless the value was incorrectly recorded in the source file.

Examples

path <- system.file("examples", "iris.dta", package = "haven")read_dta(path)tmp <- tempfile(fileext = ".dta")write_dta(mtcars, tmp)read_dta(tmp)read_stata(tmp)

Read SAS files

Description

read_sas() supports both sas7bdat files and the accompanying sas7bcat filesthat SAS uses to record value labels.

Usage

read_sas(  data_file,  catalog_file = NULL,  encoding = NULL,  catalog_encoding = encoding,  col_select = NULL,  skip = 0L,  n_max = Inf,  cols_only = deprecated(),  .name_repair = "unique")

Arguments

Value

A tibble, data frame variant with nice defaults.

Variable labels are stored in the "label" attribute of each variable. It isnot printed on the console, but the RStudio viewer will show it.

write_sas() returns the inputdata invisibly.

Examples

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

Read and write SPSS files

Description

read_sav() reads both.sav and.zsav files;write_sav() creates.zsav files whencompress = TRUE.read_por() reads.por files.read_spss() uses eitherread_por() orread_sav() based on thefile extension.

Usage

read_sav(  file,  encoding = NULL,  user_na = FALSE,  col_select = NULL,  skip = 0,  n_max = Inf,  .name_repair = "unique")read_por(  file,  user_na = FALSE,  col_select = NULL,  skip = 0,  n_max = Inf,  .name_repair = "unique")write_sav(data, path, compress = c("byte", "none", "zsav"), adjust_tz = TRUE)read_spss(  file,  user_na = FALSE,  col_select = NULL,  skip = 0,  n_max = Inf,  .name_repair = "unique")

Arguments

Details

Currently haven can read and write logical, integer, numeric, characterand factors. Seelabelled_spss() for how labelled variables inSPSS are handled in R.

Value

A tibble, data frame variant with nice defaults.

Variable labels are stored in the "label" attribute of each variable.It is not printed on the console, but the RStudio viewer will show it.

write_sav() returns the inputdata invisibly.

Examples

path <- system.file("examples", "iris.sav", package = "haven")read_sav(path)tmp <- tempfile(fileext = ".sav")write_sav(mtcars, tmp)read_sav(tmp)

Read and write SAS transport files

Description

The SAS transport format is a open format, as is required for submissionof the data to the FDA.

Usage

read_xpt(  file,  col_select = NULL,  skip = 0,  n_max = Inf,  .name_repair = "unique")write_xpt(  data,  path,  version = 8,  name = NULL,  label = attr(data, "label"),  adjust_tz = TRUE)

Arguments

Value

A tibble, data frame variant with nice defaults.

Variable labels are stored in the "label" attribute of each variable.It is not printed on the console, but the RStudio viewer will show it.

If a dataset label is defined, it will be stored in the "label" attributeof the tibble.

write_xpt() returns the inputdata invisibly.

Examples

tmp <- tempfile(fileext = ".xpt")write_xpt(mtcars, tmp)read_xpt(tmp)

"Tagged" missing values

Description

"Tagged" missing values work exactly like regular R missing values exceptthat they store one additional byte of information a tag, which is usuallya letter ("a" to "z"). When by loading a SAS and Stata file, the taggedmissing values always use lower case values.

Usage

tagged_na(...)na_tag(x)is_tagged_na(x, tag = NULL)format_tagged_na(x, digits = getOption("digits"))print_tagged_na(x, digits = getOption("digits"))

Arguments

Details

format_tagged_na() andprint_tagged_na() format taggedNA's as NA(a), NA(b), etc.

Examples

x <- c(1:5, tagged_na("a"), tagged_na("z"), NA)# Tagged NA's work identically to regular NAsxis.na(x)# To see that they're special, you need to use na_tag(),# is_tagged_na(), or print_tagged_na():is_tagged_na(x)na_tag(x)print_tagged_na(x)# You can test for specific tagged NAs with the second argumentis_tagged_na(x, "a")# Because the support for tagged's NAs is somewhat tagged on to R,# the left-most NA will tend to be preserved in arithmetic operations.na_tag(tagged_na("a") + tagged_na("z"))

Internal vctrs methods

Description

Internal vctrs methods

Usage

## S3 method for class 'haven_labelled'vec_arith(op, x, y, ...)

Write SAS files

Description

write_sas() creates sas7bdat files. Unfortunately the SAS file format iscomplex and undocumented, sowrite_sas() is unreliable and in most casesSAS will not read files that it produces.

write_xpt() writes files in the open SAS transport format, which haslimitations but will be reliably read by SAS.

Usage

write_sas(data, path)

Arguments

Convert empty strings into missing values

Description

Convert empty strings into missing values

Usage

zap_empty(x)

Arguments

Value

A character vector with empty strings replaced by missing values.

See Also

Other zappers:zap_formats(),zap_label(),zap_labels(),zap_widths()

Examples

x <- c("a", "", "c")zap_empty(x)

Remove format attributes

Description

To provide some mild support for round-tripping variables between Stata/SPSSand R, haven stores variable formats in an attribute:format.stata,format.spss, orformat.sas. If this causes problems for yourcode, you can get rid of them withzap_formats.

Usage

zap_formats(x)

Arguments

See Also

Other zappers:zap_empty(),zap_label(),zap_labels(),zap_widths()

Zap variable labels

Description

Removes variable label, leaving unlabelled vectors as is.

Usage

zap_label(x)

Arguments

See Also

zap_labels() to remove value labels.

Other zappers:zap_empty(),zap_formats(),zap_labels(),zap_widths()

Examples

x1 <- labelled(1:5, c(good = 1, bad = 5), label = "rating")x1zap_label(x1)x2 <- labelled_spss(c(1:4, 9), label = "score", na_values = 9)x2zap_label(x2)# zap_label also works with data framesdf <- tibble::tibble(x1, x2)str(df)str(zap_label(df))

Zap value labels

Description

Removes value labels, leaving unlabelled vectors as is. Use this if youwant to simply drop alllabels from a data frame.

Zapping labels fromlabelled_spss() also removes user-defined missingvalues by default, replacing with standardNAs. Use theuser_na argumentto override this behaviour.

Usage

zap_labels(x, ...)## S3 method for class 'haven_labelled_spss'zap_labels(x, ..., user_na = FALSE)

Arguments

See Also

zap_label() to remove variable labels.

Other zappers:zap_empty(),zap_formats(),zap_label(),zap_widths()

Examples

x1 <- labelled(1:5, c(good = 1, bad = 5))x1zap_labels(x1)x2 <- labelled_spss(c(1:4, 9), c(good = 1, bad = 5), na_values = 9)x2zap_labels(x2)# Keep the user defined missing valueszap_labels(x2, user_na = TRUE)# zap_labels also works with data framesdf <- tibble::tibble(x1, x2)dfzap_labels(df)

Zap special missings to regular R missings

Description

This is useful if you want to convert tagged missing values from SAS orStata, or user-defined missings from SPSS, to regular RNA.

Usage

zap_missing(x)

Arguments

Examples

x1 <- labelled(  c(1, 5, tagged_na("a", "b")),  c(Unknown = tagged_na("a"), Refused = tagged_na("b")))x1zap_missing(x1)x2 <- labelled_spss(  c(1, 2, 1, 99),  c(missing = 99),  na_value = 99)x2zap_missing(x2)# You can also apply to data framesdf <- tibble::tibble(x1, x2, y = 4:1)dfzap_missing(df)

Remove display width attributes

Description

To provide some mild support for round-tripping variables between SPSSand R, haven stores display widths in an attribute:display_width. If thiscauses problems for your code, you can get rid of them withzap_widths.

Usage

zap_widths(x)

Arguments

See Also

Other zappers:zap_empty(),zap_formats(),zap_label(),zap_labels()