diff --git a/NEWS.md b/NEWS.md index 054502fe..36f16c49 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,10 @@ # haven (development version) +* Documentation for `read_*()` functions now more clearly explains that + labelled vectors are an intermediate representation, and points users to + `as_factor()` and `zap_labels()` when preparing imported categorical + variables for analysis (#741). + * `col_select` in the `read_*()` functions now correctly implements the tidyselect interface. Columns will be returned in the order specified in `col_select` and can be renamed, e.g. `col_select = c(new = old)` (#685). diff --git a/R/haven-sas.R b/R/haven-sas.R index af880f55..6d270368 100644 --- a/R/haven-sas.R +++ b/R/haven-sas.R @@ -27,6 +27,13 @@ #' 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. #' +#' Value labels from a catalog file are preserved with the [labelled()] class. +#' Labelled vectors are an intermediate representation that preserves the +#' original value labels, not a regular R factor. Convert labelled categorical +#' variables with [as_factor()], or remove value labels with [zap_labels()] if +#' you need plain R vectors for analysis. See `vignette("semantics")` for more +#' details. +#' #' @export #' @examples #' path <- system.file("examples", "iris.sas7bdat", package = "haven") diff --git a/R/haven-spss.R b/R/haven-spss.R index 0c1a6b8f..9cd352be 100644 --- a/R/haven-spss.R +++ b/R/haven-spss.R @@ -21,6 +21,13 @@ #' 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. #' +#' Value labels are preserved with the [labelled()] class, or +#' [labelled_spss()] when `user_na = TRUE`. Labelled vectors are an +#' intermediate representation that preserves the original value labels, not a +#' regular R factor. Convert labelled categorical variables with [as_factor()], +#' or remove value labels with [zap_labels()] if you need plain R vectors for +#' analysis. See `vignette("semantics")` for more details. +#' #' `write_sav()` returns the input `data` invisibly. #' @name read_spss #' @examples diff --git a/R/haven-stata.R b/R/haven-stata.R index 369d8a58..85b3dd18 100644 --- a/R/haven-stata.R +++ b/R/haven-stata.R @@ -59,6 +59,12 @@ #' 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. #' +#' Value labels are preserved with the [labelled()] class. Labelled vectors are +#' an intermediate representation that preserves the original value labels, +#' not a regular R factor. Convert labelled categorical variables with +#' [as_factor()], or remove value labels with [zap_labels()] if you need plain +#' R vectors for analysis. See `vignette("semantics")` for more details. +#' #' If a dataset label is defined in Stata, it will stored in the "label" #' attribute of the tibble. #' diff --git a/man/read_dta.Rd b/man/read_dta.Rd index adc62a97..09a6d2eb 100644 --- a/man/read_dta.Rd +++ b/man/read_dta.Rd @@ -121,6 +121,12 @@ 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. +Value labels are preserved with the \code{\link[=labelled]{labelled()}} class. Labelled vectors are +an intermediate representation that preserves the original value labels, +not a regular R factor. Convert labelled categorical variables with +\code{\link[=as_factor]{as_factor()}}, or remove value labels with \code{\link[=zap_labels]{zap_labels()}} if you need plain +R vectors for analysis. See \code{vignette("semantics")} for more details. + If a dataset label is defined in Stata, it will stored in the "label" attribute of the tibble. diff --git a/man/read_sas.Rd b/man/read_sas.Rd index 3a806d41..51e576d0 100644 --- a/man/read_sas.Rd +++ b/man/read_sas.Rd @@ -64,6 +64,13 @@ 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. + +Value labels from a catalog file are preserved with the \code{\link[=labelled]{labelled()}} class. +Labelled vectors are an intermediate representation that preserves the +original value labels, not a regular R factor. Convert labelled categorical +variables with \code{\link[=as_factor]{as_factor()}}, or remove value labels with \code{\link[=zap_labels]{zap_labels()}} if +you need plain R vectors for analysis. See \code{vignette("semantics")} for more +details. } \description{ \code{read_sas()} supports both sas7bdat files and the accompanying sas7bcat files diff --git a/man/read_spss.Rd b/man/read_spss.Rd index 16daa671..a30f2e9d 100644 --- a/man/read_spss.Rd +++ b/man/read_spss.Rd @@ -129,6 +129,13 @@ 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. +Value labels are preserved with the \code{\link[=labelled]{labelled()}} class, or +\code{\link[=labelled_spss]{labelled_spss()}} when \code{user_na = TRUE}. Labelled vectors are an +intermediate representation that preserves the original value labels, not a +regular R factor. Convert labelled categorical variables with \code{\link[=as_factor]{as_factor()}}, +or remove value labels with \code{\link[=zap_labels]{zap_labels()}} if you need plain R vectors for +analysis. See \code{vignette("semantics")} for more details. + \code{write_sav()} returns the input \code{data} invisibly. } \description{