setupfile: Create setup files for SPSS, Stata, SAS and R

In DDIwR: DDI with R

Description

This function creates a setup file, based on a list of variable and value labels.

Usage

setupfile(lbls = "", type = "all", csv = "", miss = "", uniqueid = "",
          SD = "", delimiter = ",", OS = "windows", outfile = "",
          forcenum = c(""), ...)

Arguments

lbls	The list object containing the variable and value labels as separate components, or a path to the directory where these objects are located, for batch processing.
type	The type of setup file, can be: "SPSS", "Stata", "SAS", "R", or "all" (default).
csv	The original dataset, on the basis of which the SPSS setup file commands are created, or a path to the directory where the .csv files are located, for batch processing.
miss	A vector of missing values, or missing labels.
uniqueid	Character, the name of the unique identifier variable
SD	The row delimiter for the Stata commands, can be for example "" or ";"
delimiter	The column delimiter to be used for reading the .csv file, default is ","
OS	The target operating system, for the eol - end of line separator.
outfile	Character, the name of the setup file being created.
forcenum	A vector of column names which should be forced as numeric.
...	Other arguments (not used in this function).

Details

If type = "all", it will produce once setup file for each supported type. All created setup files will be saved in a directory called "Setup Files" which (if not already found) will be created in the user's current working directory.

The argument miss expects either:
- a vector of missing values (e.g. -1, -2, -3), or
- a vector of missing labels

If batch processing multiple files, the function will inspect all files in the provided directory, and retain only those with the extension .R or .r or DDI versions with the extension .xml or .XML (it will subsequently generate an error if the .R files do not contain an object list, or if the .xml files do not contain a DDI structured metadata file).

If the metadata directory contains a subdirectory called "data" or "Data", it will match the name of the metadata file with the name of the .csv file (their names have to be *exactly* the same, irrespective of their extension).

The csv argument can provide a data.frame object produced by reading the .csv file, or a path to the directory where the .csv files are located. If the user doesn't provide something for this argument, the function will check the existence of a subdirectory called data in the directory where the metadata files are located.

The uniqueid argument is only relevant if type = "R". It is necessary to identify missing observations in different variables, based on the unique case identifiers found in the variable provided via this argument. It will generate an "attr"ibute called "missing types", which is essentially a list whose components are variable names, and each component is a list itself containing a vector of values for each missing category (type) plus the identifiers of the cases where missing values are found (and replaced with NA). It will also generate an attribute called "unique id", which points to the same name of the variable containing the unique case identifiers.

The argument SD only makes sense when type = "Stata" or type = "all", (when Stata setup files will also be generated).

In batch mode, the code starts with the argument delimiter = ",", but if the .csv file is delimited differently it will also try hard to find other delimiters which will match the variable names in the metadata file. At the initial version 0.1-0, the automatically detected delimiters include ";" and "\t".

The argument OS can be either:
"windows" (default), or "Windows", "Win", "win",
"MacOS", "Darwin", "Apple", "Mac", "mac",
"Linux", "linux".

The end of line separator changes only when the target OS is different from the running OS.

The argument outfile expects the name of the final setup file being saved on the disk. If nothing is provided, the name of the object provided for the lbls argument will be used as a filename.

The argument forcenum forces imported character variables as numeric. Sometimes, a clearly numerical variable might have string entries like "N.A." in the csv file, thus when importing the entire variables it is detected as character instead of numeric. All these string entries will be eliminated, leaving only numbers which are suitable to force the variable as numeric.

There is also an undocumented, boolean argument called saveFile, which if set to TRUE it will save an R version if the metadata was read from a DDI .xml file, in the same directory. This function uses \link{getMetadata}, where that argument is a formal one.

Value

A setup file to complement the imported raw dataset.

Examples

test <- list()

test$varlab <- list(
"ID" = "Questionnaire ID",
"V1" = "Label for the first variable",
"V2" = "Label for the second variable",
"V3" = "Label for the third variable"
)


test$vallab$V1 <- c(
"No"             =  0, 
"Yes"            =  1,
"Not answered"   = -1
)


test$vallab$V2 <- c(
"Verry little"   =  1, 
"Little"         =  2,
"So, so"         =  3,
"Much"           =  4,
"Very much"      =  5,
"Not applicable" = -7,
"Don't know"     = -8,
"Not answered"   = -9
)


test$vallab$V3 <- c(
"No"             =  0, 
"Yes"            =  1,
"Not answered"   = -1
)


# 
###   IMPORTANT:
##### make sure to set the working directory to a directory with read/write permissions
###
# setwd("/path/to/read/write/directory")


##### then run these commands
###
# path.to.csv <- file.path(system.file(package = "DDIwR"), "data", "test.csv.gz")
# miss <- c("Not applicable", "Don't know", "Not answered")
# setupfile(test, csv = path.to.csv, uniqueid = "ID",
#           miss <- c("Not applicable", "Don't know", "Not answered"))


# setupfile(test, csv = path.to.csv, type="Stata", SD=";")


##### other types of possible utilizations, using paths to specific files
### an XML file containing a DDI metadata object
## 
# setupfile("/path/to/the/metadata/file.xml", csv="/path/to/csv/file.csv")


##### if the metadata is saved to an .R file containing a list
###
# setupfile("/path/to/the/metadata/file.R", csv="/path/to/csv/file.csv")


##### or in batch mode, specifying entire directories
###
# setupfile("/path/to/the/metadata/directory", csv="/path/to/csv/directory")

DDIwR documentation built on May 2, 2019, 4:19 p.m.