Builds a validated description of a module: a chosen set of
an instrument's scales, administered and scored on its own. Supplying the
result as the module argument of a generator produces an instrument
containing only the items belonging to those scales. The items field
below always holds the original instrument numbers, whatever a
generator prints: the online exports keep those numbers, while
generate_docx_hitopsr() numbers a Word form 1 to n down the page
unless asked not to. Supplying the module again to score_hitopsr() or
reliability_hitopsr() scores the collected columns either way.
A module naming every scale holds exactly the instrument's own items –
all 405 of them for the HiTOP-SR – but it is still a module, and
generate_docx_hitopsr() frames it as one: the form is headed
"HiTOP-SR Module (v1.0)", and with randomize = TRUE it also carries a
405-row crosswalk. Supply no module at all to get the full instrument's
framing. The Qualtrics and REDCap exports are the same either way.
Use available_scales() to see which scales an instrument offers.
Usage
hitop_module(instrument = "hitopsr", scales, call = rlang::current_env())Arguments
- instrument
A string naming the instrument to build a module from. Currently only
"hitopsr"is supported. (default ="hitopsr")- scales
A character vector of scale names to keep. Names may be given either as they are printed on the instrument (
"Antisocial Behavior") or as the camelCase stems used in scored output ("antisocialBehavior"), in any mixture and ignoring case. Duplicates are dropped.- call
Internal. The environment blamed by any error this raises. A default argument is evaluated in this function's own frame, so a direct call blames
hitop_module(); the deprecatedhitop_subset()passes its own frame instead, so a bad argument there names the function the user actually wrote. (default = this function's frame)
Value
An object of class hitop_module: a list with the resolved
instrument, the canonical display scales and their camelCase stems,
the integer items kept (original instrument numbering, ascending), the
parallel reverse keying flags, and nItems.
See also
available_scales() for the scale names this accepts;
generate_docx_hitopsr(), generate_qualtrics_hitopsr(), and
generate_redcap_hitopsr(), each of which takes a module argument;
score_hitopsr() and reliability_hitopsr() for scoring the result.
Examples
# Describe a two-scale module of the HiTOP-SR
m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss"))
m
#> <hitop_module> hitopsr: 8 items from 2 scales
#> * Agoraphobia
#> * Appetite Loss
# `$items` holds the original HiTOP-SR numbers, not 1..8 -- this is the
# descriptor, not what any particular generator prints
m$items
#> [1] 66 109 118 144 202 260 291 389
# Select the collected item columns by NAME, never by position: `m$items`
# holds item numbers, which are column positions only in a frame that is
# exactly the 405 items in order. `ku_hitopsr` leads with `participant` and
# `biosex`, so `ku_hitopsr[m$items]` would quietly return the wrong columns.
collected <- ku_hitopsr[sprintf("hsr_%03d", m$items)]
ncol(collected) == m$nItems
#> [1] TRUE