Package 'eatGADS'

Description

Function to apply meta data changes to a GADSdat object specified by a change table extracted by getChangeMeta.

Usage

applyChangeMeta(changeTable, GADSdat, ...)

## S3 method for class 'varChanges'
applyChangeMeta(changeTable, GADSdat, checkVarNames = TRUE, ...)

## S3 method for class 'valChanges'
applyChangeMeta(
  changeTable,
  GADSdat,
  existingMeta = c("stop", "value", "value_new", "drop", "ignore"),
  ...
)

Arguments

Details

Values for which the change columns contain NA remain unchanged. If changes are performed on value levels, recoding into existing values can occur. In these cases, existingMeta determines how the resulting meta data conflicts are handled, either raising an error if any occur ("stop"), keeping the original meta data for the value ("value"), using the meta data in the changeTable and, if incomplete, from the recoded value ("value_new"), or leaving the respective meta data untouched ("ignore").

Furthermore, one might recode multiple old values in the same new value. This is currently only possible with existingMeta = "drop", which drops all related meta data on value level, or existingMeta = "ignore", which leaves all related meta data on value level untouched.

Value

Returns the modified GADSdat object.

Examples

# Change a variable name and label
varChangeTable <- getChangeMeta(pisa, level = "variable")
varChangeTable[1, c("varName_new", "varLabel_new")] <- c("IDstud", "Person ID")

pisa2 <- applyChangeMeta(varChangeTable, GADSdat = pisa)

Description

Recode one or multiple variables based on a lookup table created via createLookup (and potentially formatted by collapseColumns).

Usage

applyLookup(GADSdat, lookup, suffix = NULL)

Arguments

Details

If there are missing values in the column value_new, NAs are inserted as new values and a warning is issued.

The complete work flow when using a lookup table to recode multiple variables in a GADSdat could be: (0) optional: Recode empty strings to NA (necessary, if the look up table is written to excel). (1) create a lookup table with createLookup. (2) Save the lookup table to .xlsx with write_xlsx from eatAnalysis. (3) fill out the lookup table via Excel. (4) Import the lookup table back to R via read_excel from readxl. (5) Apply the final lookup table with applyLookup.

See applyLookup_expandVar for recoding a single variable into multiple variables.

Value

Returns a recoded GADSdat.

Examples

## create an example GADSdat
iris2 <- iris
iris2$Species <- as.character(iris2$Species)
gads <- import_DF(iris2)

## create Lookup
lu <- createLookup(gads, recodeVars = "Species")
lu$value_new <- c("plant 1", "plant 2", "plant 3")

## apply lookup table
gads2 <- applyLookup(gads, lookup = lu, suffix = "_r")

## only recode some values
lu2 <- createLookup(gads, recodeVars = "Species")
lu2$value_new <- c("plant 1", "plant 2", NA)
gads3 <- applyLookup(gads, lookup = lu2, suffix = "_r")

Description

Recode one or multiple variables based on a lookup table created via createLookup. In contrast to applyLookup, this function allows the creation of multiple resulting variables from a single input variable. All variables in lookup except variable and value are treated as recode columns.

Usage

applyLookup_expandVar(GADSdat, lookup)

Arguments

Details

If a variable contains information that should be split into multiple variables via manual recoding, applyLookup_expandVar can be used. If there are missing values in any recode column, NAs are inserted as new values. A warning is issued only for the first column.

The complete work flow when using a lookup table to expand variables in a GADSdat based on manual recoding could be: (1) create a lookup table with createLookup. (2) Save the lookup table to .xlsx with write_xlsx from eatAnalysis. (3) fill out the lookup table via Excel. (4) Import the lookup table back to R via read_excel from readxl. (5) Apply the final lookup table with applyLookup_expandVar.

See applyLookup for simply recoding variables in a GADSdat.

Value

Returns a recoded GADSdat.

Examples

## create an example GADSdat
example_df <- data.frame(ID = 1:6,
                        citizenship = c("germ", "engl", "germ, usa", "china",
                                        "austral, morocco", "nothin"),
                        stringsAsFactors = FALSE)
gads <- import_DF(example_df)

## create Lookup
lu <- createLookup(gads, recodeVars = "citizenship", addCol = c("cit_1", "cit_2"))
lu$cit_1 <- c("German", "English", "German", "Chinese", "Australian", NA)
lu$cit_2 <- c(NA, NA, "USA", NA, "Morocco", NA)

## apply lookup table
gads2 <- applyLookup_expandVar(gads, lookup = lu)

Description

Applies recodes as specified by a numCheck data.frame, as created by createNumCheck.

Usage

applyNumCheck(GADSdat, numCheck)

Arguments

Details

This function is currently under development.

Value

A recoded GADSdat.

Examples

# tbd

Description

Assimilate all value labels of multiple variables as part of a GADSdat or all_GADSdat object.

Usage

assimilateValLabels(GADSdat, varNames, lookup = NULL)

Arguments

Details

Assimilation can be performed using all existing value labels or a lookup table containing at least all existing value labels. Missing codes are reused based on the meta data of the first variable in varNames.

Value

Returns the GADSdat object with changed meta data and recoded values.

Examples

# Example data set
facs_df <- data.frame(id = 1:3, fac1 = c("Eng", "Aus", "Ger"),
                      fac2 = c("Ger", "Franz", "Ita"),
                      fac3 = c("Kor", "Chi", "Alg"),
                      stringsAsFactors = TRUE)
facs_gads <- import_DF(facs_df)

assimilateValLabels(facs_gads, varNames = paste0("fac", 1:3))

Description

Auto recode a variable in a GADSdat, mirroring the core functionality provided by AUTORECODE in SPSS. A lookup table containing the respective recode pairs can be applied and/or saved.

Usage

autoRecode(
  GADSdat,
  var,
  var_suffix = "",
  label_suffix = "",
  csv_path = NULL,
  template = NULL
)

Arguments

Details

Existing values are replaced with sequential numbers, and all existing value-level metadata (valLabel and missings) are dropped. This can be useful to remove confidential information from ID variables. If the original (character) values are to be preserved as valLabels, multiChar2fac should be used instead.

An existing template may be used to ensure that identical original values are recoded as the same new values. The lookup table used to recode var may also be saved as a .csv file, e.g. to be used as a template later. If both an existing template is used and the lookup table is saved, the resulting lookup table will contain the existing recodes and additional recode pairs required for the data, if any were needed.

Value

Returns a GADSdat object.

Examples

gads <- import_DF(data.frame(v1 = letters))

# auto recode without saving lookup table
gads2 <- autoRecode(gads, var = "v1", var_suffix = "_num")

# auto recode with saving lookup table
f <- tempfile(fileext = ".csv")
gads2 <- autoRecode(gads, var = "v1", var_suffix = "_num", csv_path = f)

# auto recode with applying and expanding a lookup table
gads3 <- import_DF(data.frame(v2 = c(letters[1:3], "aa")))
gads3 <- autoRecode(gads3, var = "v2", csv_path = f,
                    template = read.csv(f))

Description

Calculate a scale variable based on multiple items.

Usage

calculateScale(
  GADSdat,
  items,
  scale,
  maxNA = length(items),
  reportDescr = FALSE
)

Arguments

Details

Descriptive statistics (including Cronbach's alpha, credit to the psy package) are calculated and printed to the console. The new scale variable is automatically inserted right after the last item in the original GADSdat.

Value

Returns a GADSdat containing the newly computed variable.

Examples

##
items <- paste0("norms_", letters[1:6])
pisa_new <- calculateScale(pisa, items = items, scale = "norms")

Description

Is a secure way to cbind the data and the meta data of two GADSdat objects. Currently, only limited merging options are supported.

Usage

## S3 method for class 'GADSdat'
cbind(..., deparse.level = 1)

Arguments

Details

If there are duplicate variables (except the variables specified in the by argument), these variables are removed from y. The meta data is joined for the remaining variables via rbind.

Value

Returns a GADSdat object.

Description

Change or add missing codes of one or multiple variables as part of a GADSdat object.

Usage

changeMissings(GADSdat, varName, value, missings)

Arguments

Details

Applied to a GADSdat or all_GADSdat object, this function is a wrapper of getChangeMeta and applyChangeMeta. The function supports changing multiple missing tags (missings) as well as missing tags of multiple variables (varName) at once.

Value

Returns the GADSdat object with changed meta data.

Examples

# Set a specific value to missing
pisa2 <- changeMissings(pisa, varName = "computer_age",
                        value = 5, missings = "miss")

# Set multiple values to missing
pisa3 <- changeMissings(pisa, varName = "computer_age",
                        value = 1:4,
                        missings = c("miss", "miss", "miss", "miss"))

# Set a specific value to not missing
pisa4 <- changeMissings(pisa2, varName = "computer_age",
                        value = 5, missings = "valid")

# Add missing tags to multiple variables
pisa5 <- changeMissings(pisa, varName = c("g8g9", "computer_age"),
                        value = c(-99, -98), missings = c("miss", "miss"))

Description

Change the SPSS format of one or multiple variables as part of a GADSdat object.

Usage

changeSPSSformat(GADSdat, varName, format)

Arguments

Details

Applied to a GADSdat or all_GADSdat object, this function is a wrapper of getChangeMeta and applyChangeMeta.

SPSS format is supplied following SPSS logic. 'A' represents character variables, 'F' represents numeric variables. The number following this letter represents the maximum width. Optionally, another number can be added after a dot, representing the number of decimals in case of a numeric variable. For instance, 'F8.2' is used for a numeric variable with a maximum width of 8 with 2 decimal numbers.

Value

Returns the GADSdat object with changed meta data..

Examples

# change SPSS format for a single variable (numeric variable with no decimals)
pisa2 <- changeSPSSformat(pisa, varName = "idstud",
                          format = "F10.0")

# change SPSS format for multiple variables (numeric variable with no decimals)
pisa2 <- changeSPSSformat(pisa, varName = c("idstud", "idschool"),
                          format = "F10.0")

Description

Change or add value labels of one or multiple variables as part of a GADSdat object.

Usage

changeValLabels(GADSdat, varName, value, valLabel)

Arguments

Details

Applied to a GADSdat or all_GADSdat object, this function is a wrapper of getChangeMeta and applyChangeMeta. The function supports changing multiple value labels (valLabel) as well as value labels of multiple variables (varName) at once.

Value

Returns the GADSdat object with changed meta data.

Examples

# Change existing value labels
pisa2 <- changeValLabels(pisa, varName = "repeated",
                        value = c(1, 2),
                        valLabel = c("no grade repetition", "grade repitition"))

# Add value label to unlabeled value
mtcars_g <- import_DF(mtcars)
mtcars_g2 <- changeValLabels(mtcars_g, varName = "cyl",
                             value = c(4, 6, 8),
                             valLabel = c("four", "six", "eight"))

# Add value labels to multiple variables at once
mtcars_g3 <- changeValLabels(mtcars_g, varName = c("mpg", "cyl", "disp"),
                             value = c(-99, -98),
                             valLabel = c("missing", "not applicable"))

Description

Change variable labels of one or multiple variables as part of a GADSdat object.

Usage

changeVarLabels(GADSdat, varName, varLabel)

Arguments

Details

Applied to a GADSdat or all_GADSdat object, this function is a wrapper of getChangeMeta and applyChangeMeta.

Value

Returns the GADSdat object with changed meta data.

Examples

# Change one variable label
pisa2 <- changeVarLabels(pisa, varName = "repeated",
                         varLabel = c("Has a grade been repeated?"))

# Change multiple variable labels
pisa2 <- changeVarLabels(pisa, varName = c("repeated", "gender"),
                         varLabel = c("Has a grade been repeated?",
                                      "Student gender"))

Description

Change variable names of a GADSdat or all_GADSdat object.

Usage

changeVarNames(GADSdat, oldNames, newNames, checkVarNames = TRUE)

Arguments

Details

Applied to a GADSdat or all_GADSdat object, this function is a wrapper of getChangeMeta and applyChangeMeta

Value

Returns the GADSdat object with changed variable names.

Examples

# Change multiple variable name
pisa2 <- changeVarNames(pisa, oldNames = c("idstud", "idschool"),
                        newNames = c("IDstud", "IDschool"))

Description

Function to check if variable names and labels, value labels and missing codes comply with SPSS requirements for meta data.

Usage

check4SPSS(GADSdat)

Arguments

Details

The function measures the length of variable names ("varNames_length", maximum of 64 characters) variable labels ("varLabels", maximum of 256 characters), value labels ("valLabels", maximum of 120 characters). Furthermore, missing codes are counted ("missings", maximum of three missing codes for character variables) and special characters are flagged in variable names ("varNames_special"). Check results are reported back on variable level, with the exception of "valLabels", which is a list with entries per violating variable.

Value

Returns a list with the entries "varNames_special", "varNames_length", "varLabels", "valLabels" and "missings".

See Also

Other dataset compliance checks: check4Stata()

Examples

# Change example data set (create a violating label)
pisa2 <- changeVarLabels(pisa, varName = "computer_age",
                        varLabel = paste(rep("3", 125), collapse = ""))

check4SPSS(pisa2)

Description

This function performs all relevant checks to assess if a GADSdat complies with all of Stata's dataset requirements. Run this before exporting a dataset as .dta, using write_stata.

Usage

check4Stata(GADSdat, version = c("Stata", "Stata 19/BE", "Stata 19/MP"))

Arguments

Details

Specifically, the following requirements are tested:

Not complying with the marked (*) requirements will prevent a dataset from being exported to a .dta file. Issues with unmarked requirements will be solved automatically by truncating.

Limits to different aspects of the dataset vary between versions of the software. By default (version = "Stata"), compliance with the limits for Stata 19/SE is checked. Checks against the limits for Stata 19/BE or Stata 19/MP can be requested by specifying version with the corresponding string. For more details, see program_limits.

Value

Either NULL if all checks are passed successfully, or a list of all check results (see details for explanations of the keywords) if any problem was detected.

See Also

Other dataset compliance checks: check4SPSS()

Examples

check4Stata(pisa)

Description

Check value labels for (a) value labels with no occurrence in the data (checkEmptyValLabels) and (b) values with no value labels (checkMissingValLabels).

Usage

checkEmptyValLabels(
  GADSdat,
  vars = namesGADS(GADSdat),
  valueRange = NULL,
  output = c("list", "data.frame")
)

checkMissingValLabels(
  GADSdat,
  vars = namesGADS(GADSdat),
  classes = c("integer"),
  valueRange = NULL,
  output = c("list", "data.frame")
)

Arguments

Details

NAs are excluded from this check. Designated missing codes are reported normally.

Value

Returns a list of length vars or a data.frame.

Functions

• checkEmptyValLabels(): check for superfluous value labels

• checkMissingValLabels(): check for missing value labels

Examples

# Check a categorical and a metric variable
checkMissingValLabels(pisa, vars = c("g8g9", "age"))
checkEmptyValLabels(pisa, vars = c("g8g9", "age"))

# Check while defining a specific value range
checkMissingValLabels(pisa, vars = c("g8g9", "age", "idschool"),
              valueRange = c(0, 5))
checkEmptyValLabels(pisa, vars = c("g8g9", "age", "idschool"),
              valueRange = c(0, 5))

Description

Function to check if SPSS format statements are specified correctly in a GADSdat object.

Usage

checkFormat(GADSdat, type = "SPSS", changeFormat = TRUE)

Arguments

Details

The function compares SPSS format statements "format" and actual character length and decimal places of all variables in a GADSdat object and its meta data information. Mismatches are reported and can be automatically adjusted.

Value

Returns a GADSdat object.

Examples

# Change example meta information (create a value label with incorrect missing code)
pisa2 <- checkFormat(pisa)

Description

Check a GADSdat object for any occurrences of labeled whole-number values that would be too large for R to handle if they were coerced as.integer().

Usage

checkIntOverflow(GADSdat)

Arguments

Details

According to its documentation, R can only handle integer values of up to (roughly) $\pm 2 \times 10^9$ (2,147,483,647 to be exact; c.f. .Machine$integer.max). This restriction is relevant when exporting a GADSdat to .dta and only when any value exceeding the limit is also labeled (or tagged as missing). This is because Stata only accepts labeled integer (not labeled floating-point; c.f. checkLabeledFractionals() in this package) values. haven's write_dta function will therefore try to coerce any labeled values as.integer(). Unlabeled values, however, will stay generic numeric values that have a higher limit.

Value

Returns a data.frame, listing the affected varNames, the large whole-number values, their respective missings tags, and whether they actually occur in the data (empty). The rownums of the affected rows in GADSdat$labels are also provided in a separate column as a fail safe.

Examples

# Introduce a fractional value into meta data
pisa2 <- changeMissings(GADSdat = pisa,
                        varName = "schtype",
                        value = 9999999999,
                        missings = "miss")
eatGADS:::checkIntOverflow(pisa2)

Description

Check a GADSdat object for any occurrences of fractional values in its metadata, including both "truly" labeled values and values tagged as missings.

Usage

checkLabeledFractionals(GADSdat)

Arguments

Details

This function is mainly useful to ensure a data set can be saved as a .dta file. Unlike, for example, SPSS, Stata only allows for integer values (and so-called extended missing values) to be labeled (Stata manual: 12.6.3). Trying to export (meta) data with labeled fractional values would therefore cause problems and run into an error from haven's write_dta function.

Value

Returns a data.frame, listing the affected varNames, the labeled fractional values, their respective missings tags, and whether they actually occur in the data (empty).

Examples

# Introduce a fractional value into meta data
pisa2 <- recodeGADS(GADSdat = pisa,
                    varName = "schtype",
                    oldValues = 2,
                    newValues = .5)
eatGADS:::checkLabeledFractionals(pisa2)

Description

Functions to check if missings are tagged and labeled correctly in a GADSdat object.

Usage

checkMissings(
  GADSdat,
  missingLabel = "missing",
  addMissingCode = TRUE,
  addMissingLabel = FALSE
)

checkMissingsByValues(GADSdat, missingValues = -50:-99, addMissingCode = TRUE)

Arguments

Details

checkMissings() compares value labels (valLabels) and missing tags (missings) of a GADSdat object and its meta data information. checkMissingsByValues() compares labeled values (value) and missing tags (missings) of a GADSdat object and its meta data information. Mismatches are reported and can be automatically adjusted. Note that all checks are only applied to the meta data information, not the actual data. For detecting missing value labels, see checkMissingValLabels.

Value

Returns a GADSdat object with - if specified - modified missing tags.

Functions

• checkMissings(): compare missing tags and value labels

• checkMissingsByValues(): compare missing tags and values in a certain range

Examples

# checkMissings
pisa2 <- changeValLabels(pisa, varName = "computer_age",
                        value = 5, valLabel = "missing: No computer use")

pisa3 <- checkMissings(pisa2)

# checkMissingsByValues
pisa4 <- changeValLabels(pisa, varName = "computer_age",
                        value = c(-49, -90, -99), valLabel = c("test1", "test2", "test3"))

pisa5 <- checkMissingsByValues(pisa4, missingValues = -50:-99)

Description

This function checks if both data bases perform identical joins via foreign keys, if they contain the same variable names and if these variables have the same value labels. Results of this comparison are reported on data table level as messages and as an output list.

Usage

checkTrendStructure(filePath1, filePath2)

Arguments

Details

An error is thrown if the key structure or the data table structure differs between the two data bases. Differences regarding meta data for missing value labels and for variables labels (and formatting) are ignored.

Reported differences regarding meta data can be inspected further via inspectMetaDifferences.

Value

Returns a report list.

Description

Function to check if a variable is unique for all cases of an identifier variable.

Usage

checkUniqueness(GADSdat, varName, idVar)

Arguments

Details

For example if missing values are multiple imputed and data is stored in a long format, checking the uniqueness of a variable within an identifier can be tricky. This function automates this task.

Value

Returns either TRUE if the variable is unique within each value for idVar or a GADSdat object including the not unique cases.

Examples

## create an example GADSdat
iris2 <- iris
iris2$Species <- as.character(iris2$Species)
gads <- import_DF(iris2, checkVarNames = FALSE)

## check uniqueness
checkUniqueness(gads, varName = "Sepal.Length", idVar = "Species")

Description

Function to check if a variable is unique for all cases of an identifier variable. This is a fast and more efficient version of checkUniqueness which always returns a logical, non missing value of length one.

Usage

checkUniqueness2(GADSdat, varName, idVar, impVar)

Arguments

Details

For example if missing values are multiple imputed and data is stored in a long format, checking the uniqueness of a variable within an identifier can be tricky. This function automates this task via reshaping the data into wide format and testing equality among the reshaped variables. Similar functionality (via matrices) is covered by lme4::isNested, which is more general and performs similarly.

Value

Returns a logical of length one.

Examples

## create an example GADSdat
l <- 1000
long_df <- data.table::data.table(id = sort(rep(1:l, 15)),
                               v1 = sort(rep(1:l, 15)),
                                 imp = rep(1:15, l))
gads <- import_DF(long_df)
## check uniqueness
checkUniqueness2(gads, varName = "v1", idVar = "id", impVar = "imp")

Description

Check if the value or variable labels of a GADSdat comply with the length limits imposed by SPSS or Stata.

Usage

checkValLabels(
  GADSdat,
  charLimits = c("SPSS", "Stata"),
  vars = namesGADS(GADSdat),
  printLength = 40
)

checkVarLabels(
  GADSdat,
  charLimits = c("SPSS", "Stata"),
  vars = namesGADS(GADSdat),
  printLength = 40
)

Arguments

Details

If more than one program name is given in charLimits, the most restrictive limit will be applied. For details about program-specific limits, see program_limits.

Please note that setting printLength to NULL (and thereby deactivating label truncation) might not actually result in the printing of the full length of the exceedingly long labels if you are using RStudio. The program's own limits on the number of characters printed to the console may still apply (see Stack Overflow).

Value

A data.frame, reporting every (truncated) long varLabel/valLabel, their respective length in the relevant unit and the varName in which they occur. For checkValLabels, the labeled value, as well as whether that value actually occurs in the data (empty), is also reported.

Functions

• checkValLabels(): Check value labels for length limits.

• checkVarLabels(): Check variable labels for length limits.

Examples

# check value labels
pisa2 <- pisa
pisa2$labels[4, "valLabel"] <- paste0(rep("abcdefg", 4300), collapse = "")
eatGADS:::checkValLabels(pisa2)

# check variable labels
pisa2$labels[1, "varLabel"] <- paste0(rep("abcdefg", 12), collapse = "")
eatGADS:::checkVarLabels(pisa2)

Description

Function to look for occurrences of a specific value in a GADSdat.

Usage

checkValue(GADSdat, value, vars = namesGADS(GADSdat))

Arguments

Details

The function checks occurrences of a specific value in a set of variables (default: all variables) in the GADSdat and outputs a vector containing the count of occurrences for all variables in which the value occurs. It explicitly supports checking for NA.

Value

A named integer.

Examples

# for all variables in the data
checkValue(pisa, value = 99)

# only for specific variables in the data
checkValue(pisa, vars = c("idschool", "g8g9"), value = 99)

Description

Checks names for SQLite column name conventions and SPSS/Stata variable name limits, and applies appropriate variable name changes to GADSdat or all_GADSdat objects.

Usage

checkVarNames(
  GADSdat,
  checkKeywords = TRUE,
  checkDots = TRUE,
  checkDuplicates = TRUE,
  charLimits = NULL
)

Arguments

Details

Invalid column names in a SQLite data base include

• SQLite keywords (see sqlite_keywords),

• column names with a "." in it and

• duplicate variable names which arise from SQLite being case insensitive.

The corresponding variable name changes are

• appending the suffix "Var" to all SQLite keywords,

• changing all "." in variable names to "_", and

• appending "_2" to case insensitive duplicated variable names.

Note that avoiding "." in variable names is beneficial for multiple reasons, such as avoiding confusion with S3 methods in R and issues when exporting to Stata.

Variable name length limits

The length of variable names is limited to 64 bytes in SPSS and to 32 characters in Stata. If more than one program name is provided in charLimits, the most restrictive among the chosen limits will be applied. Variable names exceeding that limit will be truncated and marked with the suffix "_tr".

Value

Returns the original object with updated variable names.

Examples

# Change example data set (create an invalid variable name)
pisa2 <- changeVarNames(pisa, oldNames = "computer_age",
                        newNames = "computer.age")

pisa3 <- checkVarNames(pisa2)

Description

Deprecated. The cached data base is now cleaned when the R sessions ends automatically.

Usage

clean_cache(tempPath = tempdir())

Arguments

Details

Cleans the temporary cache, specified by tempdir(). This function had to be executed at the end of an R session if getGADS_fast or getTrendGADS with fast = TRUE had been used.

Value

Returns nothing.

Description

Clone a variable as part of a GADSdat object.

Usage

cloneVariable(
  GADSdat,
  varName,
  new_varName,
  label_suffix = "",
  checkVarName = TRUE
)

Arguments

Details

The variable is simply duplicated and assigned a new name.

Value

Returns a GADSdat.

Examples

# duplicate the variable schtype
pisa_new <- cloneVariable(pisa, varName = "schtype", new_varName = "schtype_new")

Description

Collapse two columns or format a single column of a lookup table created by createLookup.

Usage

collapseColumns(lookup, recodeVars, prioritize)

Arguments

Details

If a lookup table is created by createLookup, different recoding columns can be specified by the addCols argument. This might be the case if two rater suggest recodes or one rater corrects recodes by another rater in a separate column. After the recoding columns have been filled out, collapseColumns can be used to either:

(a) Collapse two recoding columns into one recoding column. This might be desirable, if the two columns contain missing values. prioritize can be used to specify, which of the two columns should be prioritized if both columns contain valid values.

(b) Format the lookup table for applyLookup, if recodeVars is a single variable. This simply renames the single variable specified under recodeVars.

Value

Returns a data.frame that can be used for applyLookup, with the columns:

Examples

## (a) Collapse two columns
# create example recode data.frame
lookup_raw <- data.frame(variable = c("var1"), value = c("germa", "German", "dscherman"),
           recode1 = c(NA, "English", "German"),
           recode2 = c("German", "German", NA), stringsAsFactors = FALSE)

# collapse columns
lookup <- collapseColumns(lookup_raw, recodeVars = c("recode1", "recode2"), prioritize = "recode2")

## (b) Format one column
# create example recode data.frame
lookup_raw2 <- data.frame(variable = c("var1"), value = c("germa", "German", "dscherman"),
           recode1 = c("German", "German", "German"), stringsAsFactors = FALSE)

# collapse columns
lookup2 <- collapseColumns(lookup_raw2, recodeVars = c("recode1"))

Description

Recode an labeled integer variable (based on an multiple choice item), according to a character variable (e.g. an open answer item).

Usage

collapseMC_Text(
  GADSdat,
  mc_var,
  text_var,
  mc_code4text,
  var_suffix = "_r",
  label_suffix = "(recoded)"
)

Arguments

Details

Multiple choice variables can be represented as labeled integer variables in a GADSdat. Multiple choice items with a forced choice frequently contain an open answer category. However, sometimes open answers overlap with the existing categories in the multiple choice item. collapseMC_Text allows recoding the multiple choice variable based on the open answer variable.

mc_code4text indicates when entries in the text_var should be used. Additionally, entries in the text_var are also used when there are missings on the mc_var. New values for the mc_var are added in the meta data, while preserving the initial ordering of the value labels. Newly added value labels are sorted alphabetically.

For more details see the help vignette: vignette("recoding_forcedChoice", package = "eatGADS").

Value

Returns a GADSdat containing the newly computed variable.

Examples

# Example gads
example_df <- data.frame(ID = 1:5, mc = c("blue", "blue", "green", "other", "other"),
                        open = c(NA, NA, NA, "yellow", "blue"),
                        stringsAsFactors = FALSE)
example_df$mc <- as.factor(example_df$mc)
gads <- import_DF(example_df)

# recode
gads2 <- collapseMC_Text(gads, mc_var = "mc", text_var = "open",
                        mc_code4text = "other")

Description

Recode multiple variables (representing a single multiple choice item) based on multiple character variables (representing a text field).

Usage

collapseMultiMC_Text(
  GADSdat,
  mc_vars,
  text_vars,
  mc_var_4text,
  var_suffix = "_r",
  label_suffix = "(recoded)",
  invalid_miss_code = -98,
  invalid_miss_label = "Missing: Invalid response",
  notext_miss_code = -99,
  notext_miss_label = "Missing: By intention"
)

Arguments

Details

If a multiple choice item can be answered with ticking multiple boxes, multiple variables in the data set are necessary to represent this item. In this case, an additional text field for further answers can also contain multiple values at once. However, some of the answers in the text field might be redundant to the dummy variables. collapseMultiMC_Text allows to recode multiple MC items of this kind based on multiple text variables. The recoding can be prepared by expanding the single text variable (createLookup and applyLookup_expandVar) and by matching the dummy variables to its underlying values stored in variable labels (matchValues_varLabels).

The function recodes the dummy variables according to the character variables. Additionally, the mc_var_4text variable is recoded according to the final status of the text_vars (exception: if the text variables were originally NA, mc_var_4text is left as it was).

Missing values in the character variables can be represented either by NAs or by empty characters. The multiple choice variables specified with mc_vars can only contain the values 0, 1 and missing codes. The value 1 must always represent "this category applies". If necessary, use recodeGADS for recoding.

For cases for which the text_vars contain only values that can be recoded into the mc_vars, all new text_vars are given specific missing codes (see invalid_miss_code and invalid_miss_label). All remaining NAs on the character variables are given a specific missing code (notext_miss_code).

Value

Returns a GADSdat containing the newly computed variables.

Examples

# Prepare example data
mt2 <- data.frame(ID = 1:4, mc1 = c(1, 0, 0, 0), mc2 = c(0, 0, 0, 0), mc3 = c(0, 1, 1, 0),
                  text1 = c(NA, "Eng", "Aus", "Aus2"), text2 = c(NA, "Franz", NA, "Ger"),
                  stringsAsFactors = FALSE)
mt2_gads <- import_DF(mt2)
mt3_gads <- changeVarLabels(mt2_gads, varName = c("mc1", "mc2", "mc3"),
                            varLabel = c("Lang: Eng", "Aus spoken", "other"))

## All operations (see also respective help pages of functions for further explanations)
mc_vars <- matchValues_varLabels(mt3_gads, mc_vars = c("mc1", "mc2", "mc3"),
            values = c("Aus", "Eng", "Eng"), label_by_hand = c("other" = "mc3"))

out_gads <- collapseMultiMC_Text(mt3_gads, mc_vars = mc_vars,
             text_vars = c("text1", "text2"), mc_var_4text = "mc3")

out_gads2 <- multiChar2fac(out_gads, vars = c("text1_r", "text2_r"))

final_gads <- remove2NAchar(out_gads2, vars = c("text1_r_r", "text2_r_r"),
                              max_num = 1, na_value = -99, na_label = "missing: excessive answers")

Description

Compare multiple variables of two GADSdat or all_GADSdat objects.

Usage

compareGADS(
  GADSdat_old,
  GADSdat_new,
  varNames,
  output = c("list", "data.frame", "aggregated")
)

Arguments

Details

Returns "all equal" if the variable is identical across the objects or a data.frame containing a frequency table with the values which have been changed. Especially useful for checks after recoding.

Value

Returns either a list with "all equal" and data.frames or a single data.frame.

Examples

# Recode a GADS
pisa2 <- recodeGADS(pisa, varName = "schtype",
                        oldValues = 3, newValues = 9)
pisa2 <- recodeGADS(pisa2, varName = "language",
                        oldValues = 1, newValues = 15)

# Compare
compareGADS(pisa, pisa2,
            varNames = c("ganztag", "schtype", "language"), output = "list")
compareGADS(pisa, pisa2,
            varNames = c("ganztag", "schtype", "language"), output = "data.frame")
compareGADS(pisa, pisa2,
             varNames = c("ganztag", "schtype", "language"), output = "aggregated")

Description

Create a composite variable out of two variables.

Usage

composeVar(GADSdat, sourceVars, primarySourceVar, newVar, checkVarName = TRUE)

Arguments

Details

A common use case for creating a composite variable is if there are multiple sources for the same information. For example, a child and the parents are asked about the child's native language. In such cases a composite variable contains information from both variables, meaning that one source is preferred and the other source is used to substitute missing values.

Value

The modified GADSdat.

Examples

# example data
dat <- data.frame(ID = 1:4,
nat_lang_child = c("Engl", "Ger", "missing", "missing"),
nat_lang_father = c("Engl", "Engl", "Ger", "missing"),
stringsAsFactors = TRUE)
gads <- import_DF(dat)
changeMissings(gads, "nat_lang_child", value = 3, missings = "miss")
changeMissings(gads, "nat_lang_father", value = 3, missings = "miss")

# compose variable
composeVar(gads, sourceVars = c("nat_lang_child", "nat_lang_father"),
           primarySourceVar = "nat_lang_child", newVar = "nat_lang_comp")

Description

Convert a character vector, all character variables in a data.frame or selected variables in a GADSdat to upper ("uppper"), lower ("lower"), or first letter upper and everything else lower case ("upperFirst").

Usage

convertCase(x, case = c("lower", "upper", "upperFirst"), ...)

## S3 method for class 'GADSdat'
convertCase(x, case = c("lower", "upper", "upperFirst"), vars, ...)

Arguments

Value

Returns the converted object.

Methods (by class)

• convertCase(GADSdat): convert case for GADSdats

Examples

# for character
convertCase(c("Hi", "HEllo", "greaT"), case = "upperFirst")

# for GADSdat
input_g <- import_DF(data.frame(v1 = 1:3, v2 = c("Hi", "HEllo", "greaT"),
                          stringsAsFactors = FALSE))
convertCase(input_g, case = "upperFirst", vars = "v2")

Description

Creates a relational data base containing hierarchically stored data with meta information (e.g. value and variable labels).

Usage

createGADS(allList, pkList, fkList, filePath)

Arguments

Details

Uses createDB from the eatDB package to create a relational data base. For details on how to define keys see the documentation of createDB.

Value

Creates a data base in the given path, returns NULL.

Examples

# see createDB vignette

Description

Extract unique values from one or multiple variables of a GADSdat object for recoding (e.g. via an Excel spreadsheet).

Usage

createLookup(GADSdat, recodeVars, sort_by = NULL, addCols = c("value_new"))

Arguments

Details

If recoding of one or multiple variables is more complex, a lookup table can be created for later application via applyLookup or applyLookup_expandVar. The function allows the extraction of the values of multiple variables and sorting of these unique values via variable and/or values. If addCols are specified the lookup table has to be formatted via collapseColumns, before it can be applied to recode data.

Value

Returns a data frame in long format with the following variables:

Examples

# create example GADS
dat <- data.frame(ID = 1:4, var1 = c(NA, "Eng", "Aus", "Aus2"),
                  var2 = c(NA, "French", "Ger", "Ita"),
                  stringsAsFactors = FALSE)
gads <- import_DF(dat)

# create Lookup table for recoding
lookup <- createLookup(gads, recodeVars = c("var1", "var2"), sort_by = c("value", "variable"))

# create Lookup table for recoding by multiple recoders
lookup2 <- createLookup(gads, recodeVars = c("var1", "var2"), sort_by = c("value", "variable"),
                        addCols = c("value_recoder1", "value_recoder2"))

Description

All numerical variables without value labels in a GADSdat are selected and a data.frame is created, which allows the specification of minima and maxima.

Usage

createNumCheck(GADSdat)

Arguments

Details

This function is currently under development.

Value

A data.frame with the following variables:

Examples

# tbd

Description

Create an empty variable as part of a GADSdat object.

Usage

createVariable(GADSdat, varName, checkVarName = TRUE)

Arguments

Value

Returns a GADSdat.

Examples

# create a new variable
pisa_new <- createVariable(pisa, varName = "new_variable")

Description

Drop rows with duplicate IDs in a GADSdat object based on numbers of missing values.

Usage

dropDuplicateIDs(GADSdat, ID, varNames = setdiff(namesGADS(GADSdat), ID))

Arguments

Details

If duplicate IDs occur, it is often desirable to keep the row with the least missing information. Therefore, dropDuplicateIDs drops rows based on number of missing values on the specified variables (varNames).

If multiple rows have the same number of missing values, a warning is issued and the first of the respective rows is kept.

Value

Returns the GADSdat with duplicate ID rows removed.

Examples

# create example data set
gads_ori <- import_DF(data.frame(id_var = c(1, 2, 5, 4, 4),
  var1 = c(1, 2, -99, 1, -99)))
gads_ori <- changeMissings(gads_ori, varName = "var1",
  value = -99, missings = "miss")

# drop duplicate IDs
dropDuplicateIDs(gads_ori, ID = "id_var")

Description

Convert a set of dummy variables into a set of character variables.

Usage

dummies2char(GADSdat, dummies, dummyValues, charNames, checkVarNames = TRUE)

Arguments

Details

A set of dummy variables is transformed to an equal number of character variables. The character variables are aligned to the left and the remaining character variables are set to NA. For each new variable the missing codes of the respective dummy variable are reused.

Value

Returns a GADSdat.

Examples

## create an example GADSdat
dummy_df <- data.frame(d1 = c("eng", "no eng", "eng"),
                      d2 = c("french", "french", "no french"),
                      d3 = c("no ger", "ger", "no ger"),
                      stringsAsFactors = TRUE)
dummy_g <- import_DF(dummy_df)

## transform dummy variables
dummy_g2 <- dummies2char(dummy_g, dummies = c("d1", "d2", "d3"),
                        dummyValues = c("english", "french", "german"),
                        charNames = c("char1", "char2", "char3"))

Description

Set all values within one or multiple variables to NA.

Usage

emptyTheseVariables(GADSdat, vars, label_suffix = "")

Arguments

Value

Returns the recoded GADSdat.

Examples

# empty multiple variables
pisa2 <- emptyTheseVariables(pisa, vars = c("idstud", "idschool"))

Description

Run tests to check whether two GADSdat objects are (nearly) equal. equalData compares variable names, number of rows in the data, and data differences. equalMeta compares variable names and meta data differences. equalGADS combines both functions. All functions produce a test report in list format.

Usage

equalGADS(
  target,
  current,
  id = NULL,
  metaExceptions = c("display_width", "labeled"),
  tolerance = sqrt(.Machine$double.eps)
)

equalData(target, current, id = NULL, tolerance = sqrt(.Machine$double.eps))

equalMeta(target, current, metaExceptions = c("display_width", "labeled"))

Arguments

Details

More detailed checks for individual variables can be performed via inspectDifferences and inspectMetaDifferences.

Value

Returns a list with the following entries:

Description

haven's read_spss stores data together with meta data (e.g. value and variable labels) in a tibble with attributes on variable level. This function transforms a GADSdat object to such a tibble.

Usage

export_tibble(GADSdat)

Arguments

Details

This function is mainly intended for internal use. For further documentation see also write_spss.

Value

Returns a tibble.

Examples

pisa_tbl <- export_tibble(pisa)

Description

Extract data.frame from a GADSdat object for analyses in R. Value labels can be selectively applied via defining convertLabels and covertVariables. For extracting meta data see extractMeta.

Usage

extractData(
  GADSdat,
  convertMiss = TRUE,
  convertLabels = c("character", "factor", "numeric"),
  convertVariables = NULL,
  dropPartialLabels = TRUE
)

Arguments

Details

A GADSdat object includes actual data (GADSdat$dat) and the corresponding meta data information (GADSdat$labels). extractData extracts the data and applies relevant meta data on value level (missing conversion, value labels), so the data can be used for analyses in R. Variable labels are retained as label attributes on column level.

If factor are extracted via convertLabels == "factor", an attempt is made to preserve the underlying integers. If this is not possible, a warning is issued. As SPSS has almost no limitations regarding the underlying values of labeled integers and R's factor format is very strict (no 0, only integers increasing by + 1), this procedure can lead to frequent problems.

Value

Returns a data frame.

Examples

# Extract Data for Analysis
dat <- extractData(pisa)

# convert labeled variables to factors
dat <- extractData(pisa, convertLabels = "factor")

# convert only some variables to factor, all others remain numeric
dat <- extractData(pisa, convertLabels = "factor", convertVariables = c("schtype", "ganztag"))

# convert only some variables to character, all others remain numeric
dat <- extractData(pisa, convertLabels = "factor", convertVariables = c("schtype", "ganztag"))
# schtype is now character
table(dat$schtype)
# schtype remains numeric
table(dat$gender)

Description

Extract data.frame from a GADSdat object for analyses in R. Per default, missing codes are applied but value labels are dropped. Alternatively, value labels can be selectively applied via labels2character, labels2factor, and labels2ordered. For extracting meta data see extractMeta.

Usage

extractData2(
  GADSdat,
  convertMiss = TRUE,
  labels2character = NULL,
  labels2factor = NULL,
  labels2ordered = NULL,
  dropPartialLabels = TRUE
)

Arguments

Details

A GADSdat object includes actual data (GADSdat$dat) and the corresponding meta data information (GADSdat$labels). extractData2 extracts the data and applies relevant meta data on value level (missing tags, value labels), so the data can be used for analyses in R. Variable labels are retained as label attributes on column level.

If factor are extracted via labels2factor or labels2ordered, an attempt is made to preserve the underlying integers. If this is not possible, a warning is issued. As SPSS has almost no limitations regarding the underlying values of labeled integers and R's factor format is very strict (no 0, only integers increasing by + 1), this procedure can lead to frequent problems.

If multiple values of the same variable are assigned the same value label and the variable should be transformed to character, factor, or ordered, a warning is issued and the transformation is correctly performed.

Value

Returns a data frame.

Examples

# Extract Data for Analysis
dat <- extractData2(pisa)

# convert only some variables to character, all others remain numeric
dat <- extractData2(pisa, labels2character = c("schtype", "ganztag"))

# convert only some variables to factor, all others remain numeric
dat <- extractData2(pisa, labels2factor = c("schtype", "ganztag"))

# convert all labeled variables to factors
dat <- extractData2(pisa, labels2factor = namesGADS(pisa))

# convert somme variables to factor, some to character
dat <- extractData2(pisa, labels2character = c("schtype", "ganztag"),
                          labels2factor = c("migration"))

Description

Support for linking error data bases has been removed from eatGADS. extractDataOld provides (for the time being) backwards compatibility, so linking errors can still be merged automatically.

Usage

extractDataOld(
  GADSdat,
  convertMiss = TRUE,
  convertLabels = "character",
  dropPartialLabels = TRUE,
  convertVariables = NULL
)

Arguments

Details

See extractData for the current functionality.

Value

Returns a data frame.

Description

Function to extract a single GADSdat from an all_GADSdat object.

Usage

extractGADSdat(all_GADSdat, name)

Arguments

Details

GADSdat objects can be merged into a single all_GADSdat object via mergeLabels. This function, performs the reverse action, extracting a single GADSdat object.

Value

Returns an GADSdat object.

Examples

# see createGADS vignette

Description

Extract meta data (e.g. variable and values labels) from an eatGADS object. This can be a GADSdat, an all_GADSdat, a labels data.frame, or the path to an existing data base.

Usage

extractMeta(GADSobject, vars = NULL)

Arguments

Details

Meta data is stored tidily in all GADSdat objects as a separate long format data frame. This information can be extracted for a single or multiple variables.

Value

Returns a long format data frame with meta information.

Examples

# Extract Meta data from data base
db_path <- system.file("extdata", "pisa.db", package = "eatGADS")
extractMeta(db_path, vars = c("schtype", "sameteach"))

# Extract Meta data from loaded/imported GADS
extractMeta(pisa, vars = c("schtype", "sameteach"))

Description

Extract or remove variables and their meta data from a GADSdat object.

Usage

extractVars(GADSdat, vars)

removeVars(GADSdat, vars)

Arguments

Details

Both functions simply perform the variable removal or extraction from the underlying data.frame in the GADSdat object followed by calling updateMeta.

Value

Returns a GADSdat object.

Examples

## create an example GADSdat
example_df <- data.frame(ID = 1:4,
                        age = c(12, 14, 16, 13),
                        citizenship1 = c("German", "English", "Polish", "Chinese"),
                        citizenship2 = c(NA, "German", "Chinese", "Polish"),
                        stringsAsFactors = TRUE)
gads <- import_DF(example_df)

## remove variables from GADSdat
gads2 <- removeVars(gads, vars = c("citizenship2", "age"))

## extract GADSdat with specific variables
gads3 <- extractVars(gads, vars = c("ID", "citizenship1"))

Description

Convert a factor variable with n levels to n dummy variables.

Usage

fac2dummies(GADSdat, var)

Arguments

Details

Newly created variables are named as the original variable with the suffix "_a", "_b" and so on. Variable labels are created by using the original variable label (if available) and adding the value label of the corresponding level. All missing codes are forwarded to all dummy variables.

Value

Returns a GADSdat containing the newly computed variables.

Examples

## create an example GADSdat
suppressMessages(gads <- import_DF(iris))

## transform factor variable
gads2 <- fac2dummies(gads, var = "Species")

Description

Convert a factor variable with complex factor levels (factor levels contain combinations of other factor levels) to dummy variables. Dummy variables are coded 1 ("yes") and 0 ("no").

Usage

fac2dummies_complex(GADSdat, var)

Arguments

Details

The basic functionality of this function is analogous to fac2dummies. However, the function expects factor levels to only go to 9. Higher numbers are treated as combinations of factor levels, for example "13" as "1" and "3".

Value

Returns a GADSdat containing the newly computed variables.

Examples

## create an example GADSdat
df_fac <- data.frame(id = 1:6, fac = c("Opt a", "Opt c, Opt b", "Opt c",
"Opt b", "Opt a, Opt b", "Opt a, Opt b, Opt c"), stringsAsFactors = TRUE)
g_fac <- import_DF(df_fac)
g_fac <- recodeGADS(g_fac, varName = "fac", oldValues = c(1, 2, 3, 4, 5, 6),
                     newValues = c(1, 12, 123, 2, 3, 23))

## transform factor variable
fac2dummies_complex(g_fac, "fac")

Description

Fill imputed values in a imputed GADSdat_imp object with original, not imputed values from a GADSdat.

Usage

fillImputations(GADSdat, GADSdat_imp, varName, varName_imp = varName, id, imp)

Arguments

Details

This function only fills in missing values in the imputed variable from the not imputed variable. It provides parts of the functionality of subImputations but does not check whether values have been mistakenly imputed. However, performance is increased substantially.

Value

The modified GADSdat_imp..

Examples

# tbd

Description

Remove special characters from a character vector or a GADSdat object. Also suitable to fix encoding problems of a character vector or a GADSdat object. See details for available options.

Usage

fixEncoding(x, input = c("other", "ASCII", "windows1250", "BRISE"))

Arguments

Details

The option "other" replaces correctly encoded special signs. The option "ASCII" works for strings which were encoded presumably using UTF-8 and imported using ASCII encoding. The option "windows1250" works for strings which were encoded presumably using UTF-8 and imported using windows-1250 encoding. The option "BRISE" covers a unique case used at the FDZ at IQB.

If entries are all upper case, special characters are also transformed to all upper case (e.g., "AE" instead of "Ae").

Value

The modified character vector or GADSdat object.

Examples

fixEncoding(c("\U00C4pfel", "\U00C4PFEL", paste0("\U00DC", "ben"), paste0("\U00DC", "BEN")))

Description

Function to obtain a data frame from a GADSdat object for for changes to meta data on variable or on value level.

Usage

getChangeMeta(GADSdat, level = "variable")

Arguments

Details

Changes on variable level include variable names (varName), variable labels (varLabel), SPSS format ((format)) and display width (display_width). Changes on value level include values (value), value labels (valLabel) and missing codes (missings).

Value

Returns the meta data sheet for all variables including the corresponding change columns.

Examples

# For changes on variable level
varChangeTable <- getChangeMeta(pisa, level = "variable")

# For changes on value level
valChangeTable <- getChangeMeta(pisa, level = "value")

Description

Extracts variables from a GADS data base. Only the specified variables are extracted. Note that this selection determines the format of the data.frame that is extracted.

Usage

getGADS(vSelect = NULL, filePath)

Arguments

Details

See createDB and dbPull for further explanation of the query and merging processes.

Value

Returns a GADSdat object.

Examples

# Use data base within package
db_path <- system.file("extdata", "pisa.db", package = "eatGADS")
pisa_gads <- getGADS(db_path, vSelect = c("schtype", "sameteach"))

Description

Extracts variables from a eatGADS data base. Only the specified variables are extracted. Note that this selection determines the format of the data.frame that is extracted. CAREFUL: This function uses a local temporary directory to speed up loading the data base from a server and caches the data base locally for a running R session. The temporary data base is removed automatically when the running R session is terminated.

Usage

getGADS_fast(vSelect = NULL, filePath, tempPath = tempdir())

Arguments

Details

A random temporary directory is used for caching the data base and is removed, when the R sessions terminates. See createDB and dbPull for further explanation of the query and merging processes.

Value

Returns a GADSdat object.

Description

Get the (most restrictive) limits that SPSS and/or Stata imposes on a specific aspect of a dataset.

Usage

getProgramLimit(
  program = c("SPSS", "Stata", "Stata 19/BE", "Stata 19/MP"),
  component = c("varNames", "varLabels", "valLabels", "stringvars", "nrows", "ncols")
)

Arguments

Details

For more details about program specific limits as well as a full list, see program_limits. In program, "SPSS" implies SPSS 30, and "Stata" implies Stata 19/SE, as these are the most relevant version among the ones implemented here. If more than one program/version name is given in program, the most restrictive limit will be returned.

Value

A list of two elements: value (numeric size of the limit) and unit ("char", "byte", or "generic").

Examples

# Show all implemented limits
program_limits

# Get the specific limit on variable name lengths under SPSS
getProgramLimit("SPSS", "varNames")

# Get the variable name length limit a dataset has to adhere to to be compatible with
#  both SPSS and Stata 19/SE
getProgramLimit(c("Stata", "SPSS"), "varNames")

Description

Extracts variables from multiple eatGADS data bases. Data can then be extracted from the GADSdat object via extractData. For extracting meta data from a data base or a GADSdat object see extractMeta. To speed up the data loading, getGADS_fast is used per default.

Usage

getTrendGADS(
  filePaths,
  vSelect = NULL,
  years,
  fast = TRUE,
  tempPath = tempdir(),
  verbose = TRUE
)

Arguments

Details

This function extracts data from multiple GADS data bases. All data bases have to be created via createGADS. The data bases are joined via rbind() and a variable year is added, corresponding to the argument years. The GADSdat object can then further be used via extractData. See createDB and dbPull for further explanation of the querying and merging processes.

Value

Returns a GADSdat object.

Examples

# See getGADS vignette

Description

Support for linking error data bases has been removed from eatGADS. getGADSold provides (for the time being) backwards compatibility, so linking errors can still be extracted automatically.

Usage

getTrendGADSOld(
  filePath1,
  filePath2,
  lePath = NULL,
  vSelect = NULL,
  years,
  fast = TRUE,
  tempPath = tempdir()
)

Arguments

Details

See getGADS for the current functionality.

Value

Returns a GADSdat object.

Examples

# See getGADS vignette

Description

Function to import a data.frame object created by convertLabel for use in eatGADS. If possible, importing data via import_spss should always be preferred.

Usage

import_convertLabel(df, checkVarNames = TRUE)

Arguments

Details

convertLabel from R package eatAnalysis converts an object imported via read.spss (from the foreign package) to a data.frame with factors and variable labels stored in variable attributes.

Value

Returns a list with the actual data dat and a data frame with all meta information in long format labels.

Description

Function to import a data.frame object for use in eatGADS while extracting value labels from factors.

Usage

import_DF(df, checkVarNames = TRUE)

Arguments

Details

Factors are integers with labeled variable levels. import_DF extracts these labels and stores them in a separate meta data data.frame. See import_spss for detailed information.

Value

Returns a list with the actual data dat and a data frame with all meta information in long format labels.

Examples

dat <- import_DF(iris, checkVarNames = FALSE)

# Inspect Meta data
extractMeta(dat)

# Extract Data
dat <- extractData(dat, convertLabels = "character")

Description

Function to import a data.frame object for use in eatGADS while adding explicit variable and value meta information through separate data.frames.

Usage

import_raw(df, varLabels, valLabels = NULL, checkVarNames = TRUE)

Arguments

Details

The argument varLables has to contain exactly two variables, namely varName and varLabel. valLables has to contain exactly four variables, namely varName, value, valLabel and missings. The column value can only contain numerical values. The column missings can only contain the values "valid" and "miss". Variables of type factor are not supported in any of the data.frames.

Value

Returns a list with the actual data dat and with all meta information in long format labels.

Examples

dat <- data.frame(ID = 1:5, grade = c(1, 1, 2, 3, 1))
varLabels <- data.frame(varName = c("ID", "grade"),
                       varLabel = c("Person Identifier", "School grade Math"),
                       stringsAsFactors = FALSE)
valLabels <- data.frame(varName = c("grade", "grade", "grade"),
                       value = c(1, 2, 3),
                       valLabel = c("very good", "good", "sufficient"),
                       missings = c("valid", "valid", "valid"),
                       stringsAsFactors = FALSE)

gads <- import_raw(df = dat, varLabels = varLabels, valLabels = valLabels, checkVarNames = FALSE)

# Inspect Meta data
extractMeta(gads)

# Extract Data
dat <- extractData(gads, convertLabels = "character")

Description

Function to create a GADSdat object based on a dat data.frame and a labels data.frame.

Usage

import_raw2(dat, labels)

Arguments

Details

A GADSdat is basically a list with two elements: a dat and a labels data.frame. If these elements are separated, they can be cleanly tied together again by import_raw2. The function performs extensive checks on the integrity of the resulting GADSdat object. See import_spss and import_raw for further details.

Value

Returns a GADSdat object.

Examples

dat <- data.frame(ID = 1:5, grade = c(1, 1, 2, 3, 1))
varLabels <- data.frame(varName = c("ID", "grade"),
                       varLabel = c("Person Identifier", "School grade Math"),
                       stringsAsFactors = FALSE)
valLabels <- data.frame(varName = c("grade", "grade", "grade"),
                       value = c(1, 2, 3),
                       valLabel = c("very good", "good", "sufficient"),
                       missings = c("valid", "valid", "valid"),
                       stringsAsFactors = FALSE)

gads <- import_raw(df = dat, varLabels = varLabels, valLabels = valLabels, checkVarNames = FALSE)

# separate the GADSdat object
dat <- gads$dat
labels <- gads$labels

# rejoin it
dat <- import_raw2(dat, labels)

Description

Function to import a data.frame stored as a .RDS file while extracting value labels from factors.

Usage

import_RDS(filePath, checkVarNames = TRUE)

Arguments

Details

Factors are integers with labeled variable levels. import_RDS extracts these labels and stores them in a separate meta data data.frame. See import_DF for detailed information. This function is a wrapper around import_DF.

Value

Returns a list with the actual data dat and a data frame with all meta information in long format labels.

Description

Function to import .sav files while extracting meta information, e.g. variable and value labels.

Usage

import_spss(
  filePath,
  checkVarNames = TRUE,
  labeledStrings = c("drop", "keep", "transform"),
  encoding = NULL
)

Arguments

Details

SPSS files (.sav) store variable and value labels and assign specific formatting to variables. import_spss imports data from SPSS, while storing this meta-information separately in a long format data frame. Value labels and missing labels are used to identify missing values (see checkMissings). Time and date variables are converted to character.

In some special cases, .sav files seem to consist of a mix of different encoding types. In such cases, haven might throw an error if the encoding argument is not specified or UTF-8 is selected as encoding. To circumvent this problem we recommend using encoding = "ASCII" and fixing the resulting issues manually. For example, fixEncoding provides some fixes for encoding issues specific to the German language.

Value

Returns a list with the actual data dat and a data frame with all meta information in long format labels.

Examples

# Use spss data from within package
spss_path <- system.file("extdata", "pisa.zsav", package = "eatGADS")
pisa_gads <- import_spss(spss_path)

Description

Function to import .dta files while extracting meta information, e.g. variable and value labels.

Usage

import_stata(filePath, checkVarNames = TRUE, labeledStrings = FALSE)

Arguments

Details

Stata files (.dta) store variable and value labels and assign specific formatting to variables. import_stata imports data from Stata, while storing this meta-information separately in a long format data frame. Time and date variables are converted to character.

Value

Returns a list with the actual data dat and a data frame with all meta information in long format labels.

Description

Function to import a tibble while extracting meta information, e.g. variable and value labels.

Usage

import_tibble(
  tibble,
  checkVarNames = TRUE,
  labeledStrings = c("drop", "keep", "transform")
)

Arguments

Details

Tibbles may store variable and value labels as well as missing tags via the labelled class. import_tibble restructures this meta information separately in a long format data.frame. Value labels and missing tags are used to identify missing tags (see checkMissings). Time and date variables are converted to character.

Value

Returns a list with the actual data dat and a data frame with all meta information in long format labels.

Examples

# Use spss data from within package
spss_path <- system.file("extdata", "pisa.zsav", package = "eatGADS")
pisa_gads <- import_spss(spss_path)

Description

Deprecated. Please use relocateVariable instead.

Usage

insertVariable(GADSdat, var, after = NULL)

Arguments

Description

Inspect differences within a single GADSdat or between two GADSdat objects for a specific variable.

Usage

inspectDifferences(
  GADSdat,
  varName,
  other_GADSdat = GADSdat,
  other_varName = varName,
  id
)

Arguments

Details

Two GADSdat objects can be compared using equalGADS. If differences in the data for specific variables in the two objects occur, these variables can be further inspected using inspectDifferences. Differences on meta data-level can be inspected via inspectMetaDifferences.

Value

A list.

Examples

# create a second GADS with different data
pisa2 <- pisa
pisa2$dat$age[400:nrow(pisa$dat)] <- sample(pisa2$dat$age[400:nrow(pisa$dat)])

# inspect via equalGADS()
equalGADS(pisa, pisa2)

# inspect via inspectDifferences()
inspectDifferences(GADSdat = pisa, varName = "age", other_GADSdat = pisa2, id = "idstud")

Description

Inspect meta data differences within a single GADSdat or between two GADSdat objects or GADSdat data bases regarding a specific variable.

Usage

inspectMetaDifferences(
  GADSdat,
  varName,
  other_GADSdat = GADSdat,
  other_varName = varName
)

Arguments

Details

Two GADSdat objects can be compared using equalGADS. If meta data differences for specific variables in the two objects occur, these variables can be further inspected using inspectMetaDifferences. For data-level differences for a specific variable, see inspectDifferences.

Value

A list.

Examples

# create a second GADS with different meta data
pisa2 <- pisa
pisa2 <- changeVarLabels(pisa2, varName = "sameteach", varLabel = "Same math teacher")
pisa2 <- recodeGADS(pisa2, varName = "sameteach", oldValues = c(1, 2), newValues = c(0, 1))

# inspect via equalGADS()
equalGADS(pisa, pisa2)

# inspect via inspectMetaDifferences()
inspectMetaDifferences(GADSdat = pisa, varName = "sameteach", other_GADSdat = pisa2)

Description

Returns the variable and value labels of all variables in the eatGADS data base.

Usage

labelsGADS(filePath)

Arguments

Details

Variable, value and missing labels as stored in the original SPSS-files and factors from R files are converted to long format for storage in the data base. labelsGADS returns them as a long format data frame.

Value

Returns a long format data frame including variable names, labels, values, value labels and missing labels.

Examples

# Extract Meta data from data base
db_path <- system.file("extdata", "pisa.db", package = "eatGADS")
metaData <- labelsGADS(db_path)

Description

Using variable labels, matchValues_varLabels matches a vector of regular expressions to a set of variable names.

Usage

matchValues_varLabels(GADSdat, mc_vars, values, label_by_hand = character(0))

Arguments

Details

Multiple choice items can be stored as multiple dichotomous variables with the information about the variable stored in the variable labels. The function collapseMultiMC_Text can be used to collapse such dichotomous variables and a character variable, but requires a character vector with variables names of the multiple choice variables. matchValues_varLabels creates such a vector based on matching regular expressions (values) to variable labels.

Note that all variables in mc_vars have to be assigned exactly one value (and vice versa). If a variable name is missing in the output, an error will be thrown. In this case, the label_by_hand argument should be used to specify the regular expression variable name pair manually.

Value

Returns a named character vector. Values of the vector are the variable names in the GADSdat, names of the vector are the regular expressions.

Examples

# Prepare example data
mt2 <- data.frame(ID = 1:4, mc1 = c(1, 0, 0, 0), mc2 = c(0, 0, 0, 0), mc3 = c(0, 1, 1, 0),
                  text1 = c(NA, "Eng", "Aus", "Aus2"), text2 = c(NA, "Franz", NA, NA),
                  stringsAsFactors = FALSE)

mt2_gads <- import_DF(mt2)

mt3_gads <- changeVarLabels(mt2_gads, varName = c("mc1", "mc2", "mc3"),
                           varLabel = c("Lang: Eng", "Aus spoken", "other"))

out <- matchValues_varLabels(mt3_gads, mc_vars = c("mc1", "mc2", "mc3"),
                            values = c("Aus", "Eng", "Eng"),
                            label_by_hand = c("other" = "mc3"))

Description

Is a secure way to merge the data and the meta data of two GADSdat objects. Currently, only limited merging options are supported.

Usage

## S3 method for class 'GADSdat'
merge(
  x,
  y,
  by,
  all = TRUE,
  all.x = all,
  all.y = all,
  missingValue = NULL,
  missingValLabel = NULL,
  ...
)

Arguments

Details

If there are duplicate variables (except the variables specified in the by argument), these variables are removed from y. The meta data is joined for the remaining variables via rbind.

The function supports automatically recoding missing values created through merging with a designated missing code (missingValue) and a value label (missingValLabel).

Value

Returns a GADSdat object.

Description

Transform multiple GADSdat objects into a list ready for data base creation.

Usage

mergeLabels(...)

Arguments

Details

The function createGADS takes multiple GADSdat objects as input. The function preserves the ordering in which the objects are supplied, which is then used for the merging order in createGADS. Additionally, the separate lists of meta information for each GADSdat are merged and a data frame unique identifier is added.

Value

Returns an all_GADSdat object, which consists of list with a list of all data frames "datList" and a single data frame containing all meta data information "allLabels".

Examples

# see createGADS vignette

Description

Recode Missings to NA according to missing labels in label data.frame.

Usage

miss2NA(GADSdat)

Arguments

Details

Missings are imported as their values via import_spss. Using the value labels in the labels data.frame, miss2NA recodes these missings codes to NA. This function is mainly intended for internal use.

Value

Returns a data.frame with NA instead of missing codes.

Description

Convert one or multiple character variables to factors. If multiple variables are converted, a common set of value labels is created, which is identical across variables. Existing value labels are preserved.

Usage

multiChar2fac(
  GADSdat,
  vars,
  var_suffix = "_r",
  label_suffix = "(recoded)",
  convertCases = NULL
)

Arguments

Details

If a set of variables has the same possible values, it is desirable that these variables share the same value labels, even if some of the values do not occur on the individual variables. This function allows the transformation of multiple character variables to factors while assimilating the value labels. The SPSS format of the newly created variables is set to F10.0.

A current limitation of the function is that prior to the conversion, all variables specified in vars must have identical meta data on value level (value labels and missing tags).

If necessary, missing codes can be set after transformation via checkMissings for setting missing codes depending on value labels for all variables or changeMissings for setting missing codes for specific values in a specific variable.

The argument convertCases uses the function convertCase internally. See the respective documentation for more details.

Value

Returns a GADSdat containing the newly computed variable.

Examples

## create an example GADSdat
example_df <- data.frame(ID = 1:4,
                        citizenship1 = c("German", "English", "missing by design", "Chinese"),
                        citizenship2 = c("missing", "German", "missing by design", "Polish"),
                        stringsAsFactors = FALSE)
gads <- import_DF(example_df)

## transform one character variable
gads2 <- multiChar2fac(gads, vars = "citizenship1")

## transform multiple character variables
gads2 <- multiChar2fac(gads, vars = c("citizenship1", "citizenship2"))

## set values to missings
gads3 <- checkMissings(gads2, missingLabel = "missing")

Description

Variables names of a GADSdat object, a all_GADSdat object or a eatGADS data base.

Usage

namesGADS(GADS)

Arguments

Details

If the function is applied to a GADSdat object, a character vector with all variable names is returned. If the function is applied to a all_GADSdat object or to the path of a eatGADS data base, a named list is returned. Each list entry represents a data table in the object.

Value

Returns a character vector or a named list of character vectors.

Examples

# Extract variable names from data base
db_path <- system.file("extdata", "pisa.db", package = "eatGADS")
namesGADS(db_path)

# Extract variable names  from loaded/imported GADS
namesGADS(pisa)

Description

Order the variables in a GADSdat according to a character vector. If there are discrepancies between the two sets, a warning is issued.

Usage

orderLike(GADSdat, newOrder)

Arguments

Details

The variables in the dat and in the labels section are ordered. Variables not contained in the character vector are moved to the end of the data.

Value

Returns a GADSdat object.

Description

A small example data set from the German PISA Plus campus files as distributed by the Forschungsdatenzentrum, IQB.

Usage

pisa

Format

A data.frame with 500 rows and 133 variables, including:

idstud

Person ID variable

idschool

School ID variable

schtype

School type

...

Source

Research Data Center at the Institute for Educational Quality Improvement (2020). Programme for International Student Assessment - Plus 2012, 2013 (PISA Plus 2012-2013) - Campus File (Version 1) [Data set]. Berlin: Institute for Educational Quality Improvement. doi:10.5159/IQB_PISA_Plus_2012-13_CF_v1

Description

Different programs impose different limits to different components of their datasets. Additionally, limits may vary between software versions. This primarily applies to Stata's product tiers, but also to (very) old SPSS versions. eatGADS offers a number of check functions - chiefly check4SPSS and check4Stata as wrappers - to ensure a GADSdat complies with these limits, and can be exported into an SPSS or Stata file. Use getProgramLimit for a more convenient interface for obtaining specific limits.

Usage

program_limits

Format

A data.frame listing relevant limits (see details) imposed to datasets by SPSS and Stata.

Details

While datasets have several components and characteristics, the following were deemed the most important and their limits implemented in this package's checks:

• varNames: length of variable names

• varLabels: length of variable labels

• valLabels: length of value labels

• stringvars: length of strings in character variables

• nrows: number of observations

• ncols: number of variables

While SPSS has only one set of limits (disregarding legacy limits for older versions), Stata employs different limits for different product versions [1]. Within this package, "SPSS" always implies SPSS 30, and "Stata" implies Stata 19/SE. Limits of Stata 19/BE and Stata 19/MP are implemented as additional options. However, no additional versions of SPSS have been implemented yet.

References

[1] Stata: Comparison of limits

Description

Recode multiple values in multiple variables in a GADSdat to NA.

Usage

recode2NA(GADSdat, recodeVars = namesGADS(GADSdat), value = "")

Arguments

Details

If there are value labels given to the specified value, a warning is issued. Number of recodes per variable are reported.

If a data set is imported from .sav, character variables frequently contain empty strings. Especially if parts of the data are written to .xlsx, this can cause problems (e.g. as lookup tables from createLookup), as most function which write to .xlsx convert empty strings to NAs. recodeString2NA can be used to recode all empty strings to NA beforehand.

Value

Returns the recoded GADSdat.

Examples

# create example GADS
dat <- data.frame(ID = 1:4, var1 = c("", "Eng", "Aus", "Aus2"),
                  var2 = c("", "French", "Ger", "Ita"),
                  stringsAsFactors = FALSE)
gads <- import_DF(dat)

# recode empty strings
gads2 <- recode2NA(gads)

# recode numeric value
gads3 <- recode2NA(gads, recodeVars = "ID", value = 1:3)

Description

Recode one or multiple variables as part of a GADSdat or all_GADSdat object.

Usage

recodeGADS(
  GADSdat,
  varName,
  oldValues,
  newValues,
  existingMeta = c("stop", "value", "value_new", "drop", "ignore")
)

Arguments