Generate a Qualtrics Import File for the HiTOP-SR

Creates a text file formatted for the Qualtrics Advanced Format import tool containing the Hierarchical Taxonomy of Psychopathology - Self-Report (HiTOP-SR) items and instructions.

Usage

generate_qualtrics_hitopsr(
  file = "hitopsr_qualtrics.txt",
  block_name = "HiTOP-SR",
  id_prefix = "HSR",
  include_instructions = TRUE,
  breaks = 15,
  module = NULL,
  descriptor = NULL,
  subset = NULL
)

Arguments

file

Character string specifying the output file path. Defaults to "hitopsr_qualtrics.txt".

block_name

Character string specifying the name of the block in Qualtrics. Defaults to "HiTOP-SR".

id_prefix

Character string specifying the prefix for the question IDs. Defaults to "HSR".

include_instructions

Logical. If TRUE (default), includes the starting instructions as a descriptive text block.

breaks

Integer or NULL. The number of items to display before inserting a page break. Set to 0 or NULL to disable pagination. Defaults to 15.

module

An optional hitop_module() object restricting the file to the items of the chosen scales, keeping their original HiTOP-SR item numbers. This is deliberately unlike generate_docx_hitopsr(), whose module forms are numbered 1 to n: here an item number names a collected data column, so renumbering would rename variables in dictionaries already in the field. The zero-padding is the full instrument's for the same reason: item 4 is HSR_004 in a module file as in the complete one, never HSR_04. A module whose items, nItems, camelCase or instrument differ from a fresh hitop_module() build of its scales, or that cannot be rebuilt from its instrument and scales, is refused with an error of class hitop_module_mismatch, before any file is written. (default = NULL)

descriptor

An optional path to write a module descriptor to, beside the instrument file. The saved file records which scales the form covers and which instrument items they draw on, so read_module() hands the module straight back to score_hitopsr() at scoring time. A call passing no module writes a descriptor naming every scale, describing the full administration. Written before the instrument file, so an unwritable path is reported before any form is produced; if the instrument file then cannot be written, the descriptor is removed again, a file that was already at that path included. It must name a path of its own: an empty string, or the same path as file, is refused rather than leaving you with no descriptor and no error. Once both files are on disk the descriptor's path is announced on the console, after the message naming the import file. The descriptor's columns field holds the names that the generated file assigns to the items: the questions' [[ID:]] values, such as HSR_066 (built from id_prefix). A Qualtrics data export with the item variable names as column headers uses these names. Exported as numeric values rather than choice text, it can be scored by score_hitopsr() and reliability_hitopsr() from the module read_module() returns, with items omitted. Pass items for data whose columns carry other names, such as an export made with "Use internal IDs in header" or a question renamed after import. (default = NULL)

subset

Deprecated. The former name of module; supplying it warns. Supplying both module and subset is an error. (default = NULL)

Value

Invisibly returns the path to the created file (file).

See also

write_module() and read_module() for the descriptor file.

Examples

# Write a HiTOP-SR Qualtrics import file to a temporary location
generate_qualtrics_hitopsr(file = tempfile(fileext = ".txt"))
#> ✔ Qualtrics import file successfully created at /tmp/Rtmpmkz7jC/file1a6d6ad83605.txt

# A two-scale module, original numbering preserved (unlike the Word form)
generate_qualtrics_hitopsr(
  file = tempfile(fileext = ".txt"),
  module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss"))
)
#> ✔ Qualtrics import file successfully created at /tmp/Rtmpmkz7jC/file1a6d3c4e5dfd.txt