Import a bounded Qualtrics response export with its instrument evidence

Reads a numeric-value CSV export and a QSF instrument snapshot. The supported questions are single-answer multiple choice with explicit recodes, single or multiline text, text forms, and text fields attached to supported choices. Other question types and ambiguous mappings fail explicitly. Blanks remain missing with unknown reason. No sampling or randomization mechanism is inferred.

Usage

read_qualtrics(
  responses,
  qsf = NULL,
  dataset_id = NULL,
  unit = "response",
  roster = NULL,
  respondent_key = NULL,
  column_types = character(),
  preview = c("error", "exclude", "include"),
  expected_qsf_sha256 = NULL,
  instrument_version = NULL,
  expected_survey_id = NULL
)

Arguments

responses: Path to a CSV response export. Standard three-row Qualtrics headers and single-row headers containing import IDs are supported.
qsf: Path to the corresponding QSF instrument snapshot, or NULL for a response-only import. Without it, question codes remain uninterpreted strings unless converted explicitly; instrument identity and coding remain unknown.
dataset_id: Dataset identifier; defaults to the QSF survey ID.
unit: Observational unit for an import without an authoritative roster.
roster: Optional authoritative studyframe. Outcomes are left-joined to its complete attached roster, never substituted for its sampling or assignment facts.
respondent_key: Import ID (or normalized column name) containing the authoritative roster's single key. Required when roster is supplied.
column_types: Named character vector of explicit storage conversions, using import IDs or normalized names: string, number, integer, boolean.
preview: Policy for preview, test, offline-preview, and synthetic-panel records: error (default), exclude, or include. Incomplete genuine responses are retained under every policy.
expected_qsf_sha256: Optional QSF SHA-256 captured during collection. A mismatch fails. Without it, the instrument/export match remains unknown.
instrument_version: Optional caller-supplied instrument version. It is attributed information, not proof that respondents saw this version.
expected_survey_id: Optional expected survey ID, checked against the QSF.

Value

A studyframe with source evidence, question mappings, and import diagnostics.