Skip to contents

Register your own questionnaire

Source: R/questionnaires.R
define_questionnaire.Rd

Adds an instrument to the registry so that score_questionnaire(), check_questionnaire() and score_reliability() handle it exactly like a built-in one. Use it for a lab-specific scale, a translated or shortened form, or a published instrument this package does not ship – and put the call in a project's setup script so every analysis in that project scores it the same way.

Usage

define_questionnaire(
  key,
  name,
  scale,
  subscale,
  code = NULL,
  label = NULL,
  reverse = integer(0),
  recode = c("none", "center", "zero_base"),
  total = NULL,
  total_name = "Total",
  reference = NA_character_,
  higher = NA_character_,
  notes = character()
)

Arguments

key

Short identifier, used as the instrument argument.

name

Full name of the instrument, shown in messages and listings.

scale

Two-element vector giving the response range, e.g. c(1, 7).

subscale

Character vector, one entry per item, naming the subscale that item loads on. Use a comma-separated string ("Nausea,Oculomotor") for an item that loads on two.

code

Optional short code per item, used to refer to items in reverse_items and in a named items mapping. Defaults to item1, item2, ...

label

Optional item wording, one entry per item.

reverse

Optional item numbers that are reverse-scored.

recode

One of "none" (default), "center" (subtract the midpoint, giving the \(-3..+3\) coding of a 7-point semantic differential), or "zero_base" (subtract the minimum).

total

How to form an overall score across all items: "mean", "sum", or NULL (default) for none – which is the honest choice for a multidimensional instrument whose authors define no total.

total_name

Column name for that overall score. Default "Total".

reference

Optional citation, shown alongside the instrument.

higher

Optional one-word note on what a high score means, e.g. "better" or "worse".

notes

Optional character vector of scoring notes.

Value

Invisibly, the instrument definition.

Caution – verify the mapping against your own survey

Item numbers, item order and item polarity are properties of the sheet a study actually administered, not of the instrument in the abstract. Survey tools renumber items, translations reorder them, short forms drop them from the middle, and semantic differentials get printed with the poles the other way round.

This package applies each instrument's published scoring key, which is the right default and is still only a default. If the sheet your participants saw differed, the scores will be wrong – and wrong quietly, because a mismatched mapping raises no error and produces entirely plausible numbers.

So: run check_questionnaire() once per instrument per study and read the mapping it prints, and double-check any figure before it goes into a paper. The mapping used is also attached to the result as the "mapping" attribute, and summarised in a console note the first time each distinct mapping is scored in a session (silence it with options(colleyRstats.quiet_questionnaires = TRUE)).

A named items argument (items = c(mental = "tlx_md", ...)) removes the positional assumption altogether and is the safer choice for an export you did not lay out yourself.

See also

list_questionnaires(), score_questionnaire()

Examples

define_questionnaire(
  key = "acceptance",
  name = "Van der Laan acceptance scale",
  reference = "Van der Laan, Heino & De Waard (1997), Transp. Res. C 5(1)",
  scale = c(-2, 2),
  subscale = c(
    "Usefulness", "Satisfying", "Usefulness", "Satisfying", "Usefulness",
    "Satisfying", "Usefulness", "Satisfying", "Usefulness"
  ),
  label = c(
    "useful - useless", "pleasant - unpleasant", "bad - good",
    "nice - annoying", "effective - superfluous", "irritating - likeable",
    "assisting - worthless", "undesirable - desirable", "raising alertness - sleep-inducing"
  ),
  reverse = c(1, 2, 4, 5, 7, 9),
  higher = "better"
)
list_questionnaires()[1, ]
#>          key                          name n_items n_subscales scale higher_is
#> 1 acceptance Van der Laan acceptance scale       9           2  -2-2    better
#>                                                    reference
#> 1 Van der Laan, Heino & De Waard (1997), Transp. Res. C 5(1)