xlr (version 1.1.1)

build_mtable: Summarise a multiple response table

Description

This function can take one or two multiple response responses and generate a summary table with them. You can also cut these columns by other categorical columns by specify the cols parameter.

Usage

build_mtable(
  x,
  mcols,
  cols = NULL,
  table_title = "",
  use_questions = FALSE,
  use_NA = FALSE,
  wt = NULL,
  footnote = "",
  exclude_codes = NULL,
  exclude_label = paste0(exclude_codes, collapse = "_"),
  ...
)

Value

a xlr_table object. Use write_xlsx to write to an Excel file. See xlr_table for more information.

Arguments

x

a data frame or tidy object.

mcols

the column(s) that are multiple response questions. See the Details for more details of how these columns should be structured.

cols

the column(s) that we want to calculate the sum/percentage of and the multiple response question.

table_title

the title of the table sheet

use_questions

if the data has column labels (was a imported .sav) file, convert the column label to a footnote with the question.

use_NA

logical. whether to include NA values in the table. For more complicated NA processing post creation, we recommend using filter.

wt

Specify a weighting variable, if NULL no weight is applied.

footnote

optional parameter to pass a custom footnote to the question, this parameter overwrites use_questions.

exclude_codes

vector. Pass values to this argument if there exists values in the multiple response question but indicate someone saw the question but did not response to the value (e.g. -99, 0).

exclude_label

string. A name for the value of the seen but answered response.

...

These dots are for future extensions and must be empty.

Details

A multiple response response is a series of columns with a single unique response that stores survey data where a respondent may have chosen multiple options. This function works if this data is stored in a wide format. To have a valid multiple response column all the columns should start with the same text, and each contain a unique value. That is it has the form:

 data.frame(multi_col_1 = c(1,NA,1),
           multi_col_2 = c(1,1,1),
           multi_col_3 = c(NA,NA,1)
 )
#>   multi_col_1 multi_col_2 multi_col_3
#> 1           1           1          NA
#> 2          NA           1          NA
#> 3           1           1           1

This is how popular survey platforms such as Qualtrics output this data type. If your data is long, you will need to pivot the data before hand, we recommend using pivot_wider.

By default this function converts labelled to a xlr_vector by default (and underlying it is a character() type).

This function and its family (build_table, build_qtable) is designed to work with data with columns of type haven::labelled, which is the default format of data read with haven::read_sav/has the format of .sav. .sav is the default file function type of data from SPSS and can be exported from popular survey providers such as Qualtrics. When you read in data with haven::read_sav it imports data with the questions, labels for the response options etc.

See labelled and read_sav if you would like more details on the importing type.

Examples

library(xlr)
library(dplyr)

# You can use this function to calculate the number of people that have
# responded to the question `What is your favourite colour`
build_mtable(clothes_opinions,
             "Q2",
             table_title = "What is your favourite colour?")

# The function also lets you to see the number of NA questions (this is
# where someone doesn't answer any option)
build_mtable(clothes_opinions,
             "Q2",
             table_title = "What is your favourite colour?",
             use_NA = TRUE)

# You can also cut all questions in the multiple response functions by another
# column
build_mtable(clothes_opinions,
             "Q2",
             gender2,
             table_title = "Your favourite colour by gender")

# By setting `use_questions=TRUE` then the footnote will be the questions
# labels. This is useful to see what the question is.
# The function will try to pull out this based on the question label, and
# will manipulate try and get the correct label.
build_mtable(clothes_opinions,
             "Q2",
             gender2,
             table_title = "Your favourite colour by gender",
             use_questions = TRUE)

# It is common for your data to include 'other' responses in a multiple
# response column. You should remove the column before running build_mtable
clothes_opinions |>
  select(-Q3_other) |>
  build_mtable("Q3")

# You can also specify up to a maxium of two different multiple response
# columns.
clothes_opinions |>
  select(-Q3_other) |>
  build_mtable(c("Q2", "Q3"))

# These cam also be cut by other columns.
clothes_opinions |>
  select(-Q3_other) |>
  build_mtable(c("Q2", "Q3"),
               gender2)

# This function also supports weights and manual footnotes
clothes_opinions |>
  select(-Q3_other) |>
  build_mtable(c("Q2", "Q3"),
               gender2,
               wt = weight,
               footnote = "This is an example footnote.")

# Sometimes your survey data includes special codes that indicate a respondent
# saw the question but didn't select that option (e.g., 0 or -99). Use
# exclude_codes to filter these out from the count

# lets first change our data structure to match
# a normal set up in a survey
clothes_opinions <- clothes_opinions |>
  mutate(across(starts_with("Q2"),
               ~ if_else(is.na(.x), "0", .x))
  )

build_mtable(clothes_opinions,
             "Q2",
             table_title = "What is your favourite colour?",
             exclude_codes = 0)

# You can exclude multiple codes by passing a vector
build_mtable(clothes_opinions,
             "Q2",
             table_title = "What is your favourite colour?",
             exclude_codes = c(0, -99))

# By default, excluded codes are labeled with the codes concatenated together.
# You can provide a custom label using exclude_label
build_mtable(clothes_opinions,
             "Q2",
             use_NA = TRUE,
             table_title = "What is your favourite colour?",
             exclude_codes = 0,
             exclude_label = "Not selected")

# exclude_codes works with all other parameters including cuts and weights
build_mtable(clothes_opinions,
             "Q2",
             gender2,
             table_title = "Your favourite colour by gender",
             exclude_codes = c(0, -99),
             exclude_label = "No response",
             wt = weight)

# When working with two multiple response columns, exclude_codes applies
# to both columns
clothes_opinions |>
  select(-Q3_other) |>
  build_mtable(c("Q2", "Q3"),
               gender2,
               exclude_codes = 0,
               exclude_label = "Not selected")