Build and validate a survey specification

Usage

lss_spec(
  title,
  groups,
  languages = NULL,
  language = NULL,
  welcome = NULL,
  end_text = NULL,
  quotas = NULL
)

Arguments

title: Character. Survey title shown to respondents.
groups: List of groups. Each group is a list with title (character), optionally description (character, a localizable introduction shown above the group), and questions (list of question specifications, see Details).
languages: Character vector of language codes, the primary language first (e.g. c("fr", "en")). Defaults to "fr". See the Languages section.
language: Character. Backward-compatible alias for a single-language survey: language = "fr" is languages = "fr". Passing both is allowed only when language is languages[1].
welcome: Character vector of welcome-text paragraphs, or a single string starting with < used verbatim as HTML. Optional.
end_text: Character vector of end-page paragraphs, or a single string starting with < used verbatim as HTML. Optional.
quotas: List of end-of-survey quotas. Each element is a list with question (code of a question holding a single coded answer: "single", "dropdown", "singlecomment", "yesno", "gender" or "fivepoint"), code (the answer code that triggers the quota – a declared option code, or one of the kind's implicit codes for the fixed scales: Y/N, M/F, 1-5), message (text shown to the respondent) and optionally name and limit (a whole number at or above zero; omitted, it stays the historical zero). A quota emitted by write_lss() terminates the survey – the LimeSurvey mechanism for "if the person declines, end here".

Value

An object of class lss_spec: the validated specification with normalized questions (auto-numbered option codes filled in).

Details

Experimental. Assemble a survey specification – the authoring-side counterpart of the lss object – that write_lss() can turn into an importable LimeSurvey .lss file. The specification is validated in depth at construction time, because LimeSurvey itself imports silently: a mistyped attribute, a filter referencing a missing answer code, or a cap larger than the option list are all accepted on import and only surface once respondents hit them.

Each question is a list with fields:

code – stable technical code (letters then letters/digits, at most 20 characters), unique across the survey. Codes become variable names in the data and are pinned once fieldwork starts.
kind – the question type. Choice kinds: "single" (radio list), "dropdown", "singlecomment" (list with comment), "multiple", "ranking". Array kinds: "array" (rows and columns), "array5", "array10", "arrayyesno", "arraytrend" (rows only, the scale is implicit). Item batteries: "multitext", "multinumeric" (one field per option). Scalar kinds: "text", "shorttext", "hugetext", "numeric", "date", "yesno" (implicit Y/N), "gender" (implicit M/F), "fivepoint" (implicit 1-5). Plus "display" (text shown without input). Every kind maps to a LimeSurvey type attested by real exports; eight further LimeSurvey types are deferred, each with its own reason, in lss_kinds_deferred in the sources.
text – the question wording. mandatory – logical, default FALSE. help – optional help text shown under the wording.
options – for every kind that takes an option list (single, dropdown, singlecomment, multiple, ranking, multitext, multinumeric): list of options, each a list with text and optionally code, other = TRUE (native LimeSurvey "other" with a free-text field; single, dropdown and multiple only) and exclusive = TRUE (multiple only; unchecks every other box). Options without a code are numbered 1..n in order, skipping the other option, which LimeSurvey codes natively. An explicit code is letters and digits, and its length follows the table LimeSurvey stores the list in: 5 characters for a list emitted as answers (single, dropdown, singlecomment, ranking options, and array columns – answers.code is a varchar(5)), 20 characters for a list emitted as subquestions (multiple, multitext, multinumeric options, and array and implicit-scale array rows – questions.title is a varchar(20), the same column as a question code).
rows / columns – for array: the subquestions and the answer scale, same shape as options.
relevance – display condition in a minimal syntax: code = 1, code in [1, 2, autre], count(code) >= 2 (at least n boxes ticked in a multiple-choice question). The keyword autre designates the native "other" option. Conditions may only reference questions defined earlier in the survey.
max_answers – cap for multiple (strictly below the number of options) and ranking (at most the number of items).
other_position – where the "other" option is displayed: "end" (LimeSurvey default), "beginning", or "specific" together with other_position_code, the code of the option AFTER which "other" appears. In practice "other" usually belongs before the "none of the above"-type exclusive options, which the default position puts it after.
attributes – optional named list of extra question attributes passed through verbatim (e.g. display_columns). A name LimeSurvey stores per language (prefix, suffix, choice_title, printable_help, ...) is emitted once per declared language by write_lss(), and may be given either as one string for every language or keyed by language code.

Languages

languages declares the survey languages, the primary one first; languages[1] is the base language write_lss() emits, and every other declared language is written alongside it. Every localizable text – survey title, welcome and end texts, group titles, question texts and help, option, row and column labels, the "other" label, quota names and messages – accepts either a plain string (read as the primary language) or a named character vector or list keyed by language code:

lss_spec(
  title = c(fr = "Enquete", en = "Survey"),
  languages = c("fr", "en"),
  groups = list(list(
    title = c(fr = "Profil", en = "Profile"),
    questions = list(list(
      code = "q1", kind = "yesno",
      text = c(fr = "Etes-vous d'accord ?", en = "Do you agree?")))))
)

The spec keeps one canonical form (a named list over the declared languages) and is strict: as soon as several languages are declared, every text must supply every one of them. A missing translation is precisely what audit_lss() flags when reading a .lss, so the spec refuses to author one. write_lss() writes every declared language: languages[1] becomes the survey's base language and the others its additional languages, each localized section carrying one row per language.

Examples

spec <- lss_spec(
  title = "Demo",
  languages = "fr",
  groups = list(list(
    title = "Profil",
    questions = list(
      list(code = "consent", kind = "single", text = "Participez-vous ?",
           mandatory = TRUE,
           options = list(list(text = "Oui"), list(text = "Non"))),
      list(code = "raisons", kind = "multiple", text = "Pourquoi ?",
           relevance = "consent = 1", max_answers = 2,
           options = list(
             list(text = "Une raison"), list(text = "Une autre"),
             list(text = "Encore une"),
             list(text = "Aucune raison", exclusive = TRUE),
             list(text = "Autre raison", other = TRUE)))
    )
  ))
)
spec$groups[[1]]$questions[[2]]$options[[4]]$code
#> [1] "4"