Connect to NHES Survey Data

Opens a connection to a National Household Education Survey (NHES) data file and returns an edsurvey.data.frame with information about the file and data.

Usage

readNHES(savFiles, surveyCode = "auto", forceReread = FALSE, verbose = TRUE)

Arguments

savFiles

a character vector to the full file path(s) to the NHES extracted SPSS (*.sav) data files.

surveyCode

a character vector of the surveyCode to identify the year and survey type of the passed savFiles data file(s). The default value is set to auto which attempts to automatically identify the survey/year based on the file attributes. Occasionally, the auto lookup may be unable to determine the surveyCode and must be explicitly set by the user. The lengths of the savFiles vector and surveyCode vector must match, unless surveyCode is set to auto. To view the surveyCodes available, use the getNHES_SurveyInfo, or viewNHES_SurveyCodes function to view the codes.

forceReread

a logical value to force a rereading of all processed data. The default value of FALSE speeds up the readNHES function by using existing read-in data if already processed.

verbose

a logical value that defaults to TRUE for verbose console output that indicates progress information. If verbose = FALSE, no information will be printed.

Value

an edsurvey.data.frame if only one NHES file is specified for the savFiles argument, or an edsurvey.data.frame.list if multiple files are passed to the savFiles argument

Details

Reads in the unzipped public-use files downloaded from the NCES Online Codebook (https://nces.ed.gov/datalab/onlinecodebook) in SPSS (*.sav) format. Other sources of NHES data, such as restricted-use files or other websites, may require additional conversion steps to generate the required SPSS data format and/or explicitly setting the surveyCode parameter.

See also

downloadNHES, getNHES_SurveyInfo, and viewNHES_SurveyCodes

Author

Tom Fink

Examples

if (FALSE) { # \dontrun{
rootPath <- "~/"

#get instructions for obtaining NHES data 
downloadNHES()

#get SPSS *.sav file paths of all NHES files for 2012 and 2016
filesToImport <- list.files(path = file.path(rootPath, "NHES", c(2012, 2016)), 
                            pattern="\\.sav$", 
                            full.names = TRUE, 
                            recursive = TRUE)

#import all files to edsurvey.data.frame.list object
esdfList <- readNHES(savFiles = filesToImport, surveyCode = "auto", 
                     forceReread = FALSE, verbose = TRUE)

viewNHES_SurveyCodes() #view NHES survey codes in console

#get the full file path to the 2016 ATES NHES survey
path_ates2016 <- list.files(path = file.path(rootPath, "NHES", "2016"), 
                            pattern=".*ates.*[.]sav$", full.names = TRUE)

#explicitly setting the surveyCode parameter (if required)
esdf <- readNHES(savFiles = path_ates2016, surveyCode = "ATES_2016", 
                 forceReread = FALSE, verbose = TRUE)

#search for variables in the edsurvey.data.frame
searchSDF(string="sex", data=esdf)
} # }