Fetch Labelled Survey Data

Download Qualtrics responses through qualtRics and apply a Variable Dictionary generated by dict_generate. Export Variables are matched by response_column_id, renamed to variable_name, and labelled with question, item, level, and label metadata using sjlabelled.

Usage

fetch_labelled_survey_data(
  dict,
  extra_columns = c("externalDataReference", "startDate", "endDate"),
  exclude_findings = c("none", "definite", "validation"),
  ...,
  require_valid_dict = TRUE,
  quiet = TRUE
)

Arguments

dict

A Variable Dictionary returned by dict_generate.

extra_columns

A character vector of downloaded survey data columns to retain in the Labelled Survey Data in addition to Export Variables. Defaults to c("externalDataReference", "startDate", "endDate"). Columns absent from the downloaded data warn (naming the missing columns) and are skipped, so several candidate names can be supplied when only one is expected to be present (for example ordered id-column fallbacks). Use NULL to retain no extra columns (this also suppresses the response metadata columns described below).

exclude_findings

Which Validation Finding classes cost their rows after survey download. "none" keeps all downloaded variables represented in the Variable Dictionary. "definite" excludes only the rows whose Validation Findings are Definite Validation Findings (severity == "definite" in dict_validate output): the Export-blocking level-label codings, and the variable-name findings that make the renamed export's column identity unreliable. Rows carrying only Suggestive Validation Findings (a repaired variable_name; a gapped level run) keep their columns and stay reported by dict_validate(). "validation" excludes every row with any Validation Finding, suggestive ones included.

...

Other arguments passed to fetch_survey. Filtering arguments such as include_questions may be passed through. qualtdict owns surveyID, import_id, convert, label, and breakout_sets; passing those arguments errors because they are needed for reliable Variable Dictionary to Response Column ID matching.

require_valid_dict

Boolean. If TRUE (the default), the Variable Dictionary is checked with assert_dict_valid before any responses are downloaded, and Export-blocking Validation Findings error. Use FALSE to download from a survey known to carry them; the affected Export Variables then keep unreliable value labels. Because require_valid_dict follows ..., supply it by name.

quiet

Boolean. If TRUE, suppress routine validation messages. Defaults to TRUE.

Value

Labelled Survey Data: a data frame whose Export Variables are renamed to variable_name and annotated with labels from the Variable Dictionary.

Details

Live calls require Qualtrics credentials configured for qualtRics because response data are downloaded from the Qualtrics API. qualtdict owns the fetch_survey() settings needed for reliable Variable Dictionary to Response Column ID matching: import_id = TRUE, label = FALSE, convert = FALSE, and breakout_sets = TRUE. User-supplied passthrough arguments cannot override those settings.

By default, Labelled Survey Data includes variables with Validation Findings. Use exclude_findings when you want to explicitly remove them after download. Because quiet follows ..., supply it by name.

Export-blocking Validation Findings are checked before the download, so a defective Variable Dictionary costs no responses. The check is skipped when exclude_findings is "definite" or "validation", because every Export-blocking Response Column ID is then dropped from the Variable Dictionary after download anyway (every Export-blocking Validation Finding is a Definite Validation Finding). The pre-download check never aborts on Suggestive Validation Findings under any setting.

Unless extra_columns = NULL, Labelled Survey Data additionally carries the per-response metadata columns startDate, endDate, recordedDate, ResponseId, and Progress. These are emitted under exactly those names regardless of the source export casing: import_id = TRUE downloads them as startDate, endDate, recordedDate, _recordId, and progress, and each is normalised to its canonical name. Inclusion is best effort: any metadata column absent from the download (for example in sanitized offline fixtures) is omitted without warning rather than erroring.

Examples

if (interactive()) {
  survey_id <- "SV_XXXXXXXXXXXXXXXX"

  # Generate a dictionary
  mydict <- dict_generate(survey_id, variable_name = "question_name")
  survey_dat <- fetch_labelled_survey_data(mydict,
    unanswer_recode = -77,
    unanswer_recode_multi = 0
  )
}