Skip to contents

qualtdict

License: MIT

Qualtrics is an online survey and data collection software platform. qualtdict is a metadata and labelled-export companion to qualtRics for Qualtrics surveys.

qualtRics owns API access to Qualtrics. qualtdict owns the package workflow that turns Qualtrics metadata and import-ID response exports into:

  • a Variable Dictionary with response_column_id, row_source, qid, question_name, variable_name, and survey metadata needed for analysis;
  • Validation Findings that make dictionary consistency issues visible; and
  • Labelled Survey Data whose Export Variables are renamed to variable_name and labelled from the Variable Dictionary.

qualtdict is not a replacement downloader for qualtRics, a general survey cleaning framework, or a stable Semantic Name generator.

Installation

This package can be installed with the remotes package.

install.packages("remotes")
remotes::install_github("lyh970817/qualtdict")

Credentials And Offline Work

Live calls to dict_generate() and fetch_labelled_survey_data() require Qualtrics API credentials because they retrieve metadata and responses through qualtRics. Register credentials with qualtRics::qualtrics_api_credentials(), which qualtdict also re-exports for convenience.

library(qualtdict)

qualtRics::qualtrics_api_credentials(
  api_key = "<YOUR-QUALTRICS_API_KEY>",
  base_url = "<YOUR-QUALTRICS_BASE_URL>",
  install = TRUE
)

Package tests and documentation examples avoid private survey data. Validation, dictionary schema checks, block splitting, and labelled-export mechanics can be tested offline with synthetic dictionaries and synthetic metadata. Only live Qualtrics metadata or response downloads require credentials.

Variable Dictionary To Labelled Survey Data

Generate a Variable Dictionary from a survey ID. The dictionary keeps response_column_id as the downloaded response-column key, row_source as the Dictionary Row Source, qid as the bare Qualtrics question identifier, question_name as the raw Qualtrics naming reference, and variable_name as the final export-safe Dictionary Variable Name. Question-backed rows use row_source = "question", and flat Embedded Data Fields defined by Qualtrics metadata use row_source = "embedded_data". Scoring Variables defined by survey description metadata use row_source = "scoring", while Text-analysis Sidecars discovered from the response column map use row_source = "text_analysis". Embedded Data Field block assignment, when requested, uses the richer Survey Flow returned by fetch_description(). Scoring Variables remain unassigned by Survey Block.

survey_id <- "SV_XXXXXXXXXXXXXXXX"

dict <- dict_generate(
  survey_id,
  variable_name = "question_name"
)

Use dict_validate() to return structured Validation Findings.

validation <- dict_validate(dict)
validation$validation_findings

Then create Labelled Survey Data. qualtdict calls qualtRics::fetch_survey() with the response-column settings needed to match downloaded data back to response_column_id, then renames Export Variables to variable_name and attaches labels from the Variable Dictionary.

survey_dat <- fetch_labelled_survey_data(
  dict,
  extra_columns = c("externalDataReference", "startDate", "endDate"),
  exclude_findings = "none",
  unanswer_recode = -77,
  unanswer_recode_multi = 0
)

If Qualtrics Question Names are not suitable as analysis names, you can ask qualtdict to generate Semantic Names. Semantic Names are readable conveniences generated from survey text and metadata; they are not stable guarantees across package versions or survey text changes. For long text, Semantic Names select important words from ranked keywords and preserve those selected words in the order they appear in the naming text.

block_pattern <- function(block) {
  substring(block, 1, 3)
}

dict <- dict_generate(
  survey_id,
  variable_name = "semantic_name",
  block_pattern = block_pattern,
  block_sep = "."
)

How To Cite

If qualtdict contributes to published work, please cite it. The citation for the installed version is returned by citation().

citation("qualtdict")

Learn More