Tools, classes and methods to manipulate survey data.

Description

Tools, classes and methods to manipulate survey data.

Details

Surveydata objects have been designed to function with SPSS export data, i.e. the result of an SPSS import, foreign::read.spss(). This type of data is contained in a data.frame, with information about the questionnaire text in the variable.labels attribute. Surveydata objects keep track of the variable labels, by offering methods for renaming, subsetting, etc.

Coercion functions:

• as.surveydata()

• is.surveydata()

• as.data.frame.surveydata()

To access and modify attributes:

• pattern()

• varlabels()

To subset or merge surveydata objects:

• merge()

• Extract()

• cbind.surveydata()

To extract question text from varlabels:

• question_text()

• question_text_common()

• question_text_unique()

To fix common encoding problems:

• encToInt()

• intToEnc()

• fix_common_encoding_problems()

To clean data:

• remove_dont_know() to remove "Don't know" responses

• remove_all_dont_know() to remove "Don't know" responses from all questions

• fix_levels_01() to fix level formatting of all question with Yes/No type answers

Miscellaneous tools:

• dropout() to determine questions where respondents drop out

Author(s)

Andrie de Vries apdevries@gmail.com

Examples

library(surveydata)

# Create surveydata object

sdat <- data.frame(
    id   = 1:4,
    Q1   = c("Yes", "No", "Yes", "Yes"),
    Q4_1 = c(1, 2, 1, 2), 
    Q4_2 = c(3, 4, 4, 3), 
    Q4_3 = c(5, 5, 6, 6), 
    Q10 = factor(c("Male", "Female", "Female", "Male")),
    crossbreak  = c("A", "A", "B", "B"), 
    weight      = c(0.9, 1.1, 0.8, 1.2)
)

varlabels(sdat) <- c(
    "RespID",
    "Question 1", 
    "Question 4: red", "Question 4: green", "Question 4: blue", 
    "Question 10",
    "crossbreak",
    "weight"
  )

sv <- as.surveydata(sdat, renameVarlabels = TRUE)

# Extract specific questions
sv[, "Q1"]
sv[, "Q4"]

# Query attributes
varlabels(sv)
pattern(sv)

# Find unique questions

questions(sv)
which.q(sv, "Q1")
which.q(sv, "Q4")

# Find question text
question_text(sv, "Q1")
question_text(sv, "Q4")

question_text_common(sv, "Q4")
question_text_unique(sv, "Q4")


# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])

Extract or replace subsets of surveydata, ensuring that the varlabels stay synchronized.

Description

The surveydata package makes it easy to extract specific questions from a surveydata object. Because survey data typically has question names like "Q1_a", "Q1_b", "Q1_c" the extract method for a surveydata object makes it easy to extract all columns by simply specifying "Q1" as the argument to the column index.

Usage

## S3 method for class 'surveydata'
x[i, j, drop = FALSE]

## S3 replacement method for class 'surveydata'
x[i, j] <- value

## S3 replacement method for class 'surveydata'
x$name <- value

Arguments

Details

Extraction is similar to data frames, with three important exceptions:

• The column argument j is evaluated using which.q() and will return all columns where the column names match the pattern().

• The drop argument is FALSE. Thus the result will always be a surveydata object, even if only a single column is returned.

• All extraction methods retain the pattern and varlabels arguments.

See Also

surveydata-package, varlabels

Examples

names(membersurvey)
head(membersurvey["Q1"])
head(membersurvey[c("Q1", "Q2")])
head(membersurvey[membersurvey$Q2=="2009", c("Q1", "Q2")])

# The pattern is used to extract columns

pattern(membersurvey)

grep("Q20", names(membersurvey), value=TRUE)
head(membersurvey["Q20"])
head(membersurvey["Q20_other"])

Coerces surveydata object to data.frame.

Description

Coerces surveydata object to data.frame.

Usage

## S3 method for class 'surveydata'
as.data.frame(x, ..., rm.pattern = FALSE)

Arguments

See Also

surveydata-package

Coercion from and to surveydata.

Description

Methods for creating surveydata objects, testing for class, and coercion from other objects.

Usage

as.surveydata(
  x,
  sep = "_",
  exclude = "other",
  ptn = pattern(x),
  defaultPtn = list(sep = sep, exclude = exclude),
  renameVarlabels = FALSE
)

un_surveydata(x)

Arguments

Details

The functionun_surveydata() removes the surveydata class from the object, leaving intact the other classes, e.g. data.frame or tibble

See Also

surveydata-package, is.surveydata()

Examples

library(surveydata)

# Create surveydata object

sdat <- data.frame(
    id   = 1:4,
    Q1   = c("Yes", "No", "Yes", "Yes"),
    Q4_1 = c(1, 2, 1, 2), 
    Q4_2 = c(3, 4, 4, 3), 
    Q4_3 = c(5, 5, 6, 6), 
    Q10 = factor(c("Male", "Female", "Female", "Male")),
    crossbreak  = c("A", "A", "B", "B"), 
    weight      = c(0.9, 1.1, 0.8, 1.2)
)

varlabels(sdat) <- c(
    "RespID",
    "Question 1", 
    "Question 4: red", "Question 4: green", "Question 4: blue", 
    "Question 10",
    "crossbreak",
    "weight"
  )

sv <- as.surveydata(sdat, renameVarlabels = TRUE)

# Extract specific questions
sv[, "Q1"]
sv[, "Q4"]

# Query attributes
varlabels(sv)
pattern(sv)

# Find unique questions

questions(sv)
which.q(sv, "Q1")
which.q(sv, "Q4")

# Find question text
question_text(sv, "Q1")
question_text(sv, "Q4")

question_text_common(sv, "Q4")
question_text_unique(sv, "Q4")


# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])

Converts free format question text to datatable using the DT package.

Description

Converts free format question text to datatable using the DT package.

Usage

as_opentext_datatable(data, q)

Arguments

See Also

Other open text functions: print_opentext()

Examples

as_opentext_datatable(membersurvey, "Q33")

Combines surveydata object by columns.

Description

Combines surveydata object by columns.

Usage

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

Arguments

Methods to support dplyr verbs.

Description

The surveydata package exposes functionality to support some of the dplyr verbs, e.g. dplyr::filter(). The computation is performed by dplyr, and the resulting object is of class surveydata (as well as the dplyr result).

Usage

## S3 method for class 'surveydata'
mutate(.data, ...)

## S3 method for class 'surveydata'
as_tibble(x, ..., .name_repair, rownames)

## S3 method for class 'surveydata'
as.tbl(x, ...)

## S3 method for class 'surveydata'
select(.data, ...)

## S3 method for class 'surveydata'
arrange(.data, ...)

## S3 method for class 'surveydata'
summarise(.data, ...)

## S3 method for class 'surveydata'
summarize(.data, ...)

## S3 method for class 'surveydata'
slice(.data, ...)

Arguments

Examples

withr::with_package("dplyr", {
  membersurvey %>% 
    as_tibble() %>% 
    .[c("id", "Q1", "Q2")] %>% 
    filter(Q2 == 2009)
})

Calculates at which questions respondents drop out.

Description

The number of respondents for each question is calculated as the length of the vector, after omitting NA values.

Usage

dropout(x, summary = TRUE)

Arguments

Value

Named numeric vector of respondent counts

Examples

dropout(membersurvey[-(127:128)])

Converts a character vector to an integer vector.

Description

Conversion of character vector to integer vector. The encoding of the character vector can be specified but defaults to the current locale.

Usage

encToInt(x, encoding = localeToCharset())

Arguments

Value

An integer vector

See Also

iconv()

Other Functions to clean data: fix_common_encoding_problems(), fix_levels_01_spss(), has_dont_know(), intToEnc(), leveltest, remove_all_dont_know(), remove_dont_know()

Examples

encToInt("\xfa")

Fix common encoding problems when working with web imported data.

Description

This function tries to resolve typical encoding problems when importing web data on Windows. Typical problems occur with pound and emdash (-), especially when these originated in MS-Word.

Usage

fix_common_encoding_problems(x, encoding = localeToCharset())

Arguments

See Also

Other Functions to clean data: encToInt(), fix_levels_01_spss(), has_dont_know(), intToEnc(), leveltest, remove_all_dont_know(), remove_dont_know()

Fix level formatting of all question with Yes/No type answers.

Description

Fix level formatting of all question with Yes/No type answers.

Usage

fix_levels_01_spss(dat)

fix_levels_01_r(dat)

fix_levels_01(dat, origin = c("R", "SPSS"))

Arguments

See Also

Other Functions to clean data: encToInt(), fix_common_encoding_problems(), has_dont_know(), intToEnc(), leveltest, remove_all_dont_know(), remove_dont_know()

Deprecated functions.

Description

These functions have all been superseded with functions using snake_case function names.

• hasDK: has_dont_know()

• removeDK: remove_dont_know()

• removeAllDK: remove_all_dont_know()

• leveltestSPSS: leveltest_spss()

• leveltestR: leveltest_r()

• fixLevels01SPSS: fix_levels_01_spss()

• fixLevels01R: fix_levels_01_r()

• fixLevels01: fix_levels_01()

• qOrder: question_order()

• lapplyNames: lapply_names()

• fixCommonEncodingProblems: fix_common_encoding_problems()

Usage

hasDK(...)

removeDK(...)

removeAllDK(...)

leveltestSPSS(...)

leveltestR(...)

fixLevels01SPSS(...)

fixLevels01R(...)

fixLevels01(...)

qOrder(...)

lapplyNames(...)

fixCommonEncodingProblems(...)

qText(...)

qTextUnique(...)

qTextCommon(...)

Arguments

Tests whether levels contain "Don't know".

Description

Returns TRUE if x contains any instances of dk

Usage

has_dont_know(x, dk = "Don't Know")

Arguments

Value

TRUE or FALSE

See Also

Other Functions to clean data: encToInt(), fix_common_encoding_problems(), fix_levels_01_spss(), intToEnc(), leveltest, remove_all_dont_know(), remove_dont_know()

Converts an integer vector to a character vector.

Description

Conversion of integer vector to character vector. The encoding of the character vector can be specified but defaults to the current locale.

Usage

intToEnc(x, encoding = localeToCharset())

Arguments

Value

A character vector

See Also

iconv()

Other Functions to clean data: encToInt(), fix_common_encoding_problems(), fix_levels_01_spss(), has_dont_know(), leveltest, remove_all_dont_know(), remove_dont_know()

Examples

intToEnc(8212)

Tests whether an object is of class surveydata.

Description

Tests whether an object is of class surveydata.

Usage

is.surveydata(x)

Arguments

See Also

surveydata-package

Applies function only to named elements of a list.

Description

This is useful to clean only some columns in a list (or data.frame or surveydata object). This is a simple wrapper around lapply() where only the named elements are changed.

Usage

lapply_names(x, names, FUN, ...)

Arguments

See Also

Other Tools: question_order()

Fix level formatting of all question with Yes/No type answers.

Description

Fix level formatting of all question with Yes/No type answers.

Usage

leveltest_spss(x)

leveltest_r(x)

Arguments

See Also

Other Functions to clean data: encToInt(), fix_common_encoding_problems(), fix_levels_01_spss(), has_dont_know(), intToEnc(), remove_all_dont_know(), remove_dont_know()

Data frame with survey data of member satisfaction survey.

Description

Data frame with survey data of member satisfaction survey.

Usage

membersurvey

Format

data frame

Merge surveydata objects.

Description

The base R merge will merge data but not all of the attributes. This function also merges the variable.labels attribute.

Usage

## S3 method for class 'surveydata'
merge(x, y, ...)

Arguments

Merges variable.labels attribute from two surveydata objects

Description

Merges variable labels from two data objects. The labels from dat1 takes precedence.

Usage

merge_varlabels(dat1, dat2, new_names = union(names(dat1), names(dat2)))

Arguments

Updates names and variable.labels attribute of surveydata.

Description

Updates names and variable.labels attribute of surveydata.

Usage

## S3 replacement method for class 'surveydata'
names(x) <- value

Arguments

See Also

surveydata-package(), is.surveydata()

Returns and updates pattern attribute.

Description

The pattern attribute contains information about the separator character used to name sub-questions in the data. Survey software typically makes use of underscores to distinguish sub-questions in a grid of questions, e.g. "Q4_1", "Q4_2", "Q4_3", "Q4_other". The function pattern() returns the pattern attribute, and pattern<- updates the attribute.

Usage

pattern(x)

pattern(x) <- value

Arguments

See Also

as.surveydata(), which.q()

Other Attribute functions: varlabels()

Examples

# Extract the pattern from membersurvey

oldptn <- pattern(membersurvey)
oldptn

# The pattern is used to extract columns

names(membersurvey)
grep("Q20", names(membersurvey), value=TRUE)

head(membersurvey["Q20"])
head(membersurvey["Q20_other"])

# Define a new pattern

pattern(membersurvey) <- list(sep="_", exclude="")
head(membersurvey["Q20"])

# Reset original pattern

pattern(membersurvey) <- oldptn
rm(oldptn)

Print open text questions.

Description

Print open text questions.

Usage

print_opentext(data, q, cat = TRUE)

Arguments

See Also

Other open text functions: as_opentext_datatable()

Examples

print_opentext(membersurvey, "Q33")

Changes vector to ordered factor, adding NA levels if applicable.

Description

Changes vector to ordered factor, adding NA levels if applicable.

Usage

question_order(x)

Arguments

See Also

Other Tools: lapply_names()

Returns question text.

Description

Given a question id, e.g. "Q4", returns question text for this question. Note that this returns. The functions question_text_unique() and question_text_common() returns the unique and common components of the question text.

Usage

question_text(x, Q)

Arguments

Value

character vector

See Also

Other Question functions: question_text_common(), question_text_unique(), questions(), split_common_unique(), which.q()

Examples

# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])

Returns common element of question text.

Description

Given a question id, e.g. "Q4", finds all sub-questions, e.g. "Q4_1", "Q4_2", etc, and returns the question text that is common to each.

Usage

question_text_common(x, Q)

Arguments

Value

character vector

See Also

Other Question functions: question_text_unique(), question_text(), questions(), split_common_unique(), which.q()

Examples

# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])

Returns unique elements of question text.

Description

Given a question id, e.g. "Q4", finds all sub-questions, e.g. Q4_1, Q4_2, etc, and returns the question text that is unique to each

Usage

question_text_unique(x, Q)

Arguments

Value

character vector

See Also

Other Question functions: question_text_common(), question_text(), questions(), split_common_unique(), which.q()

Examples

# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])

Returns a list of all the unique questions in the surveydata object.

Description

In many survey systems, sub-questions take the form Q1_a, Q1_b, with the main question and sub-question separated by an underscore. This function conveniently returns all of the main questions in a surveydata() object. It does this by using the pattern() attribute of the surveydata object.

Usage

questions(x, ptn = pattern(x))

Arguments

Value

numeric vector

See Also

which.q

Other Question functions: question_text_common(), question_text_unique(), question_text(), split_common_unique(), which.q()

Examples

# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])

Removes "Do not know" and other similar words from factor levels in data frame.

Description

Removes "Do not know" and other similar words from factor levels in data frame

Usage

remove_all_dont_know(x, dk = NULL, message = TRUE)

Arguments

Value

A data frame

See Also

hasDK() and removeDK()

Other Functions to clean data: encToInt(), fix_common_encoding_problems(), fix_levels_01_spss(), has_dont_know(), intToEnc(), leveltest, remove_dont_know()

Removes "Don't know" from levels and replaces with NA.

Description

Tests the levels of x contain any instances of "Don't know". If so, replaces these levels with NA

Usage

remove_dont_know(x, dk = "Don't Know")

Arguments

Value

A factor with "Dont know" removed

See Also

Other Functions to clean data: encToInt(), fix_common_encoding_problems(), fix_levels_01_spss(), has_dont_know(), intToEnc(), leveltest, remove_all_dont_know()

Removes pattern and variable.labels from attributes list.

Description

Removes pattern and variable.labels from attributes list.

Usage

rm.attrs(x)

Arguments

Removes pattern from attributes list.

Description

Removes pattern from attributes list.

Usage

rm.pattern(x)

Arguments

Get common and unique text in question based on regex pattern identification.

Description

Get common and unique text in question based on regex pattern identification.

Usage

split_common_unique(x, ptn = NULL)

Arguments

See Also

Other Question functions: question_text_common(), question_text_unique(), question_text(), questions(), which.q()

Finds the common and unique elements in a character vector.

Description

Function takes a character string as input and find the common and unique elements. Assumes that the common element is at start of string.

Usage

strCommonUnique(string)

Arguments

Value

list of common and unique strings

Examples

test <- c("Q_1", "Q_2", "Q_3")
strCommonUnique(test)$common
strCommonUnique(test)$unique

Plots single and as multi-response questions.

Description

Plots single and as multi-response questions.

Usage

survey_plot_question(data, q)

Arguments

See Also

Other survey plotting functions: survey_plot_satisfaction(), survey_plot_yes_no()

Examples

question_text(membersurvey)

survey_plot_question(membersurvey, "Q2")
survey_plot_yes_no(membersurvey, "Q2")
survey_plot_satisfaction(membersurvey, "Q14")

Plot satisfaction questions.

Description

Plot satisfaction questions.

Usage

survey_plot_satisfaction(data, q, fun = c("net", "top3", "top2"))

Arguments

See Also

Other survey plotting functions: survey_plot_question(), survey_plot_yes_no()

Examples

question_text(membersurvey)

survey_plot_question(membersurvey, "Q2")
survey_plot_yes_no(membersurvey, "Q2")
survey_plot_satisfaction(membersurvey, "Q14")

Construct plot title from the question text, wrapping at the desired width.

Description

This creates a plot title using ⁠[ggplot2::ggtitle()]⁠. The main title is string wrapped, and the subtitle is the number of observations in the data.

Usage

survey_plot_title(data, q, width = 50)

Arguments

Plot data in yes/no format.

Description

Plot data in yes/no format.

Usage

survey_plot_yes_no(data, q)

Arguments

See Also

Other survey plotting functions: survey_plot_question(), survey_plot_satisfaction()

Examples

question_text(membersurvey)

survey_plot_question(membersurvey, "Q2")
survey_plot_yes_no(membersurvey, "Q2")
survey_plot_satisfaction(membersurvey, "Q14")

Returns and updates variable.labels attribute of surveydata object.

Description

In a surveydata object, the variable.labels attribute store metadata about the original question text (see foreign::read.spss() for details). The function varlabels() returns the variable.labels attribute of data, and varlabels(x) <- value updates this attribute.

Usage

varlabels(x)

varlabels(x) <- value

Arguments

Details

In a surveydata object, the varlabels attribute is a named character vector, where the names correspond to the names of the the columns in

See Also

surveydata-package

Other Attribute functions: pattern()

Other Attribute functions: pattern()

Examples

# Extract the variable labels from membersurvey

ms <- membersurvey[, c("id", "Q1", "Q2")]

str(ms)
varlabels(ms)
varlabels(ms)["Q2"]

# Assign a new value to the text of question 2

varlabels(ms)["Q2"] <- "When did you join?"
varlabels(ms)
str(ms["Q2"])

Identifies the columns indices corresponding to a specific question.

Description

In many survey systems, sub-questions take the form "Q1_a", "Q1_b", with the main question and sub-question separated by an underscore. This function conveniently returns column index of matches found for a question id in a surveydata object. It does this by using the pattern attribute of the surveydata object.

Usage

which.q(x, Q, ptn = pattern(x))

Arguments

See Also

questions() to return all questions matching the pattern()

Other Question functions: question_text_common(), question_text_unique(), question_text(), questions(), split_common_unique()

Examples

# Basic operations on a surveydata object, illustrated with the example dataset membersurvey

class(membersurvey)

questions(membersurvey)

which.q(membersurvey, "Q1")
which.q(membersurvey, "Q3")
which.q(membersurvey, c("Q1", "Q3"))

question_text(membersurvey, "Q3")
question_text_unique(membersurvey, "Q3")
question_text_common(membersurvey, "Q3")

# Extracting columns from a surveydata object

head(membersurvey[, "Q1"])
head(membersurvey["Q1"])
head(membersurvey[, "Q3"])
head(membersurvey[, c("Q1", "Q3")])

# Note that the result is always a surveydata object, even if only one column is extracted

head(membersurvey[, "id"])
str(membersurvey[, "id"])