Skip to content

qualtdict: Generate Variable Dictionaries and Labelled Survey Data for Qualtrics Surveys #807

Description

@lyh970817

Submitting Author Name: Yuhao Lin
Submitting Author Github Handle: @lyh970817
Repository: https://github.com/lyh970817/qualtdict
Version submitted: 0.1.0
Submission type: Standard
Editor: TBD
Reviewers: TBD

Archive: TBD
Version accepted: TBD
Language: en


  • Paste the full DESCRIPTION file inside a code block below:
Package: qualtdict
Title: Generate Variable Dictionaries and Labelled Survey Data for
    'Qualtrics' Surveys
Version: 0.1.0
Authors@R:
    person("Yuhao", "Lin", , "yuhao.lin@kcl.ac.uk", role = c("aut", "cre"),
           comment = c(ORCID = "0000-0001-6357-5731"))
Description: Generates Variable Dictionaries from 'Qualtrics'
    <https://www.qualtrics.com/about/> survey metadata and applies those
    dictionaries to create Labelled Survey Data. This package is a
    metadata and labelled-export companion to 'qualtRics', which provides
    access to 'Qualtrics' survey data and metadata via the 'Qualtrics' API
    <https://api.qualtrics.com/>.
License: MIT + file LICENSE
URL: https://github.com/lyh970817/qualtdict, https://lyh970817.github.io/qualtdict/
BugReports: https://github.com/lyh970817/qualtdict/issues
Imports:
    dplyr,
    glue,
    haven,
    purrr,
    qualtRics,
    rlang,
    sjlabelled,
    stringr,
    tibble,
    xml2
Suggests:
    covr,
    knitr,
    openNLP,
    rmarkdown,
    slowraker (>= 0.1.1),
    SnowballC,
    stringi,
    testthat (>= 3.0.0),
    tidyr
SystemRequirements: Java is needed only for POS-tag filtering via the
    suggested 'openNLP' package.
VignetteBuilder:
    knitr
Config/testthat/edition: 3
Config/testthat/start-first: dict_generate, dict_validate, fetch_labelled_survey_data
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
Config/roxygen2/version: 8.0.0

Scope

  • Please indicate which category or categories from our package fit policies this package falls under:

    • data retrieval
    • data extraction
    • data munging
    • data deposition
    • data validation and testing
    • workflow automation
    • version control
    • citation management and bibliometrics
    • scientific software wrappers
    • field and lab reproducibility tools
    • database software bindings
    • geospatial data
    • translation
    • rOpenSci internal tools
  • Explain how and why the package falls under these categories (briefly, 1–2 sentences):

qualtdict is primarily a data-munging package for the scientific workflow of managing Qualtrics survey exports. It converts complex Qualtrics metadata into an inspectable variable dictionary and applies that dictionary to response exports; its validation functions also automatically check variable-name and level-label consistency before labelled export.

  • Who is the target audience and what are scientific applications of this
    package?

The target audience is researchers, data managers, and analysts who collect data with Qualtrics and need a reproducible bridge between survey design and analysis variables. Scientific applications include producing an inspectable variable dictionary for complex surveys, preserving the identity and provenance of downloaded response columns, detecting inconsistent names or level-label mappings, and generating analysis-ready labelled survey data.

The closest package is qualtRics, on which qualtdict depends. qualtRics owns authentication, API retrieval, reading Qualtrics exports, and the Qualtrics-provided column map; it can also attach variable labels to downloaded columns. qualtdict does not reimplement that API client. Instead, it adds a metadata-driven workflow that builds a standalone variable dictionary, preserves an explicit mapping from Qualtrics Response Column IDs to analyst-facing dictionary variable names, validates dictionary consistency, and then applies the dictionary deterministically to an import-ID response export.

The added functionality includes rendering the response columns generated by complex question shapes and loop and merge structures; representing metadata-defined export variables such as embedded data fields, scoring variables, and text-analysis sidecars; export-safe name repair with recorded findings; structured validation findings; a pre-download gate for export-blocking level-label codings; and block-specific views. The relationship is therefore complementary rather than a second downloader: qualtRics retrieves Qualtrics data and metadata, while qualtdict constructs, validates, and applies the Variable Dictionary needed for a reproducible labelled-data workflow.

Yes. qualtdict does not scrape public data or expand access beyond the surveys available to the user's own Qualtrics credentials. Authentication and API transport are delegated to qualtRics; credentials are not included in package data, tests, examples, or logs. The package sends no telemetry and does not transmit survey data to any service other than the user-authorized Qualtrics API request needed to retrieve it. Tests and documentation examples use synthetic metadata and synthetic response data rather than private surveys or participant records.

  • If you made a pre-submission inquiry, please paste the link to the
    corresponding issue, forum post, or other discussion, or @tag the editor
    you contacted.

No separate pre-submission inquiry was made. This is a new submission following the administrative closure of the earlier qualtdict submission, ropensci/software-review#572. A response to the handling editor's initial comments is included below, as required by the current resubmission policy.

  • Explain reasons for any pkgcheck items which your package is unable to pass.

There are no failing pkgcheck items. The latest full pkgcheck run for commit 41769c40 reported 100% test coverage, all goodpractice linters passing, and no R CMD check errors or warnings.

pkgcheck identifies several noteworthy structural percentiles, including source and test lines, number of internal functions, and function-call network size. These are informational rather than failed checks. The exported API is small, while most internal functions are short, narrowly scoped transformations used to make distinct Qualtrics metadata and response-column shapes explicit; the correspondingly large test suite records those behaviours.

Response to the earlier submission

The earlier submission was put on hold and then closed on 20 June 2024 before any external reviewer was assigned. The following addresses the handling editor's initial comments in submission #572 before new reviewers are recruited.

ml01 — reviewer expertise

Reviewers with any of the following expertise would be especially useful:

  1. Qualtrics metadata, the Qualtrics API, or the qualtRics package;
  2. survey-data management and Variable Dictionaries in social, behavioural,
    or health research; or
  3. R package architecture, metadata normalisation, and data validation.

I do not have a strong preference for particular individuals and am happy for the editor to recruit reviewers while applying rOpenSci's conflict-of-interest rules.

ml02 — dependencies that appeared unused

The hard dependency set has been reviewed and reduced from 17 packages in the 2023 submission to 10. Dependencies used only by the optional Semantic Name route (slowraker, SnowballC, stringi, tidyr, and openNLP) are now in Suggests, and the default variable_name = "question_name" path does not load them. Other obsolete dependencies, including crul and magrittr, were removed.

The remaining non-obvious case is haven. The current CRAN release of sjlabelled calls haven::is_tagged_na() on the named-label path exercised by qualtdict, so removing haven currently breaks that path. The reason for retaining it, including the temporary importFrom(haven, read_xpt) namespace declaration used to avoid the “Namespace in Imports field not imported from” NOTE, is disclosed in ADR 0011. The upstream fix has been merged in sjlabelled PR #70, and qualtdict issue #29 tracks removal of both haven and the temporary declaration once a CRAN release contains that fix.

ml03 — whole-package imports

Whole-package imports were replaced with explicit importFrom() declarations generated by roxygen2. The current NAMESPACE contains no import(package) entries, and the current goodpractice checks pass.

ml04 — library() or require() in package code

Package code no longer calls library() or require(). Optional capabilities use guarded namespace checks, and the current static analyses report no such linter finding.

ml05 — noisy test output

Routine messages and progress bars are controlled by quiet arguments, which default to quiet operation in the exported dictionary and validation functions. The test suite now runs without the large volume of incidental console output reported in 2023.

ml06 — test warnings

The unexpected warnings reported in 2023 were removed or made explicit in the tests where a warning is part of the public behaviour. Current CI and pkgcheck complete with no R CMD check warnings, and the test suite has 100% coverage.

ml07 — RStudio project

A package-configured qualtdict.Rproj is now committed to the repository.

Technical checks

Confirm each of the following by checking the box.

This package:

Use of Generative AI

  • Generative AI tools were used to produce some of the material in this submission.

Generative AI tools, principally OpenAI ChatGPT and Codex and Anthropic Claude, were used during the 2026 redevelopment to help analyse the codebase, propose implementations and refactors, draft and review tests, and edit documentation. ChatGPT was also used to help prepare this submission text.

I made and retained control over the package scope, public API, domain model, acceptance or rejection of proposed changes, and release decisions. I reviewed and edited all accepted generated material, inspected the test and check results, and remain responsible for the submitted code and documentation.

Publication options

  • Do you intend for this package to go on CRAN?

  • Do you intend for this package to go on Bioconductor?

  • Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options
  • The package is novel and will be of interest to the broad readership of the journal.
  • The manuscript describing the package is no longer than 3000 words.
  • You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code).
  • (Scope: Do consider MEE's Aims and Scope for your manuscript. We make no guarantee that your manuscript will be within MEE scope.)
  • (Although not required, we strongly recommend having a full manuscript
    prepared when you submit here.
    )
  • (Please do not submit your package separately to Methods in Ecology and
    Evolution.
    )

Code of conduct

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions