Questionnaire Task

Version: v1 (current)

A flexible survey and assessment tool for collecting self-report data, demographic information, and structured responses from participants.

Overview

The Questionnaire task provides a comprehensive system for administering surveys, psychological assessments, demographic forms, and any structured collection of participant responses. It supports multiple question types (multiple choice, scales, text input, etc.), conditional logic, validation rules, and branching.

Unlike behavioral tasks that measure performance, questionnaires capture subjective experiences, personal information, attitudes, symptoms, and self-reported characteristics. They're essential for correlating behavioral data with individual differences, screening participants, and collecting contextual information.

The task is commonly used for:

Demographic surveys: Age, education, language, medical history
Psychological assessments: Depression (BDI), anxiety (GAD-7), personality (Big Five)
Task ratings: Difficulty, effort, motivation, strategy use
Screening: Eligibility criteria, exclusion factors
Manipulation checks: Verify experimental manipulations worked
Debriefing: Post-study experience and feedback

Why Researchers Use This Task

Individual Differences: Correlate task performance with traits, symptoms, demographics
Participant Characterization: Describe sample characteristics
Screening: Determine eligibility or group assignment
Subjective Experience: Capture ratings of difficulty, confidence, engagement
Validated Scales: Administer standardized psychological assessments
Mixed Methods: Combine quantitative behavior with qualitative self-report

Current Implementation Status

Fully Implemented:

✅ 12 question types: scale, numeric, text, textarea, mcq, multi, dichotomous, date, slider, matrix, ranking, image_choice
✅ Required and optional questions
✅ Validation rules (min/max length for text, min/max value for numeric)
✅ Conditional display logic (eq/neq/gt/lt operators)
✅ Multi-page questionnaires (questions_per_page setting)
✅ Progress tracking (progress bar with percentage)
✅ Matrix/grid questions (fully implemented)
✅ Visual Analog Scales / sliders (fully implemented)
✅ Randomized question AND option order
✅ Per-question response time tracking
✅ RTL support
✅ Image-based choice questions
✅ Ranking questions
✅ Question templates (Demographics, Likert-5, Likert-7, VAS, Yes/No)
✅ Import/Export questions as JSON
✅ Flat CSV-ready data export

Configuration Parameters

Questionnaire Structure

Parameter	Type	Default	Description
Title	string	''	Questionnaire title
Randomize Questions	boolean	false	Randomize question presentation order
Show Progress	boolean	false	Display progress bar during participation
Show Question Numbers	boolean	true	Display Q1, Q2... numbering
Questions Per Page	number	0	Questions per page (0 = all on one page)
Questions	array	[]	Array of question objects

Question Object Structure

{
  id: "q1",                           // Unique identifier
  type: "mcq",                        // Question type
  text: "What is your age range?",   // Question text
  required: true,                     // Must be answered
  options: [                          // For option-based types (mcq, multi, dichotomous, ranking, image_choice)
    { label: "18-25", marker: "age_18_25", image_url: "..." },
    { label: "26-35", marker: "age_26_35" }
  ],
  min: 1,                             // For numeric/slider: minimum value
  max: 100,                           // For numeric/slider: maximum value
  step: 1,                            // For numeric/slider: step size
  label_min: "Not at all",            // For slider: left endpoint label
  label_max: "Extremely",             // For slider: right endpoint label
  scale_labels: ["Never", "Rarely", "Sometimes", "Often", "Always"], // For scale: option labels
  items: ["Item 1", "Item 2"],        // For matrix: row items
  min_length: 10,                     // For text/textarea: minimum character count
  max_length: 500,                    // For text/textarea: maximum character count
  randomize_options: false,           // Randomize option order
  condition: {                        // Conditional display
    question_id: "q0",
    operator: "eq",                   // eq, neq, gt, lt
    value: "Yes"
  }
}

Question Types

Type	Description	Response Format
`scale`	Likert-style rating scale	Number
`numeric`	Numeric input	Number
`text`	Short text input	String
`textarea`	Long-form text	String
`mcq`	Multiple choice (single selection)	String (option marker)
`multi`	Multiple selection checkboxes	Array of strings (option markers)
`dichotomous`	Yes/No question	String (option marker)
`date`	Date picker	Date string (YYYY-MM-DD)
`slider`	Visual Analog Scale / continuous	Number
`matrix`	Grid with shared scale for multiple items	Object (keyed by item index)
`ranking`	Rank items in order	Array of strings (ordered items)
`image_choice`	Image-based selection	String (option marker)

Presentation Parameters

Parameter	Type	Default	Description
Show Progress	boolean	false	Display progress bar
Show Question Numbers	boolean	true	Display Q1, Q2... numbering
Questions Per Page	number	0	Questions per page (0 = all on one page)

Meta-Translation Keys

All participant-facing labels are customizable through meta-translations:

Key	Default	Description
`questionnaire_submit`	Submit	Submit button text
`questionnaire_previous`	Previous	Previous page button
`questionnaire_required_indicator`	*	Required field symbol
`questionnaire_yes`	Yes	Dichotomous default Yes label
`questionnaire_no`	No	Dichotomous default No label
`questionnaire_required_fields_error`	Please answer all required questions...	Validation error message
`questionnaire_progress`	Question `{current}` of `{total}`	Progress text template

Data Output

Markers and Responses

The task records several markers during the questionnaire and one response object per question on submission.

Markers (questionnaire_order):

{
  "type": "questionnaire_order",
  "ts": "2024-01-01T00:00:01.000Z",
  "hr": 1234.56,
  "data": {
    "order": ["q1", "q2", "q3"]
  }
}

Markers (stimulus_shown):

{
  "type": "stimulus_shown",
  "ts": "2024-01-01T00:00:01.000Z",
  "hr": 1234.56,
  "data": {
    "order": ["q1", "q2", "q3"]
  }
}

Additional markers logged via the task's marker base:

{task}_q{N} -- Participant interacted with question N (1-based)
{task}_q{N}_o{M} -- Participant selected option M (1-based) on question N (for option-based question types)

Markers (questionnaire_submitted):

{
  "type": "questionnaire_submitted",
  "ts": "2024-01-01T00:00:30.000Z",
  "hr": 30234.56
}

Response Data (one per question on submission):

{
  "id": "q1",
  "marker": "task_0_q1",
  "index": 0,
  "type": "scale",
  "value": 4,
  "latency_ms": 2345,
  "display_duration_ms": 5678
}

Field	Type	Description
`id`	string	Question identifier (e.g., `"q1"`)
`marker`	string	Question marker string
`index`	number	Question display index (0-based)
`type`	string	Question type
`value`	varies	Participant's answer (number for scale/numeric/slider, string for mcq/text/date, array for multi/ranking, object for matrix)
`latency_ms`	number/null	Time from question display to first interaction
`display_duration_ms`	number/null	Total time question was displayed

Summary Artifacts

Full data artifact (questionnaire_{index}.json):

{
  "title": "Survey Title",
  "answers": {
    "q1": 4,
    "q2": "Yes",
    "q3": ["Option A", "Option B"]
  },
  "questions": [],
  "order": ["q1", "q2", "q3"],
  "response_times": {
    "q1": {
      "latency_ms": 2345,
      "display_duration_ms": 5678
    }
  },
  "total_duration_ms": 45000
}

Flat CSV-ready artifact (questionnaire_{index}_flat.json):

{
  "q1": 4,
  "q1_latency_ms": 2345,
  "q1_display_duration_ms": 5678,
  "q2": "Yes",
  "q2_latency_ms": 1234,
  "q2_display_duration_ms": 3456,
  "total_duration_ms": 45000
}

Example Questionnaires

Demographics Survey

{
  title: "Background Information",
  questions: [
    {
      id: "age",
      type: "numeric",
      text: "What is your age?",
      required: true,
      min: 18,
      max: 100
    },
    {
      id: "gender",
      type: "mcq",
      text: "Gender",
      options: [
        { label: "Male", marker: "male" },
        { label: "Female", marker: "female" },
        { label: "Non-binary", marker: "nonbinary" },
        { label: "Prefer not to say", marker: "prefer_not_to_say" }
      ],
      required: true
    },
    {
      id: "education",
      type: "mcq",
      text: "Highest level of education completed",
      options: [
        { label: "Less than high school", marker: "less_than_hs" },
        { label: "High school diploma", marker: "hs_diploma" },
        { label: "Some college", marker: "some_college" },
        { label: "Associate degree", marker: "associate" },
        { label: "Bachelor's degree", marker: "bachelor" },
        { label: "Master's degree", marker: "master" },
        { label: "Doctoral degree", marker: "doctoral" }
      ],
      required: true
    },
    {
      id: "handedness",
      type: "mcq",
      text: "Which hand do you primarily use for writing?",
      options: [
        { label: "Right", marker: "right" },
        { label: "Left", marker: "left" },
        { label: "Both equally", marker: "both" }
      ],
      required: true
    }
  ]
}

Post-Task Ratings

{
  title: "Task Experience",
  questions: [
    {
      id: "difficulty",
      type: "scale",
      text: "How difficult did you find the task?",
      scale_labels: ["Very Easy", "", "", "", "", "", "Very Difficult"],
      required: true
    },
    {
      id: "effort",
      type: "scale",
      text: "How much effort did you put into the task?",
      scale_labels: ["Minimal Effort", "", "", "", "", "", "Maximum Effort"],
      required: true
    },
    {
      id: "strategy",
      type: "textarea",
      text: "Please describe any strategies you used to complete the task.",
      required: false,
      max_length: 500
    }
  ]
}

Screening Questionnaire with Conditional Logic

{
  title: "Eligibility Screening",
  questions: [
    {
      id: "color_vision",
      type: "dichotomous",
      text: "Do you have normal or corrected-to-normal color vision?",
      options: [
        { label: "Yes", marker: "yes" },
        { label: "No", marker: "no" }
      ],
      required: true
    },
    {
      id: "color_deficiency_type",
      type: "mcq",
      text: "What type of color vision deficiency do you have?",
      options: [
        { label: "Red-green", marker: "red_green" },
        { label: "Blue-yellow", marker: "blue_yellow" },
        { label: "Complete color blindness", marker: "complete" },
        { label: "Unsure", marker: "unsure" }
      ],
      required: true,
      condition: {
        question_id: "color_vision",
        operator: "eq",
        value: "no"
      }
    },
    {
      id: "vision_correction",
      type: "dichotomous",
      text: "Do you wear glasses or contact lenses?",
      options: [
        { label: "Yes", marker: "yes" },
        { label: "No", marker: "no" }
      ],
      required: true
    },
    {
      id: "wearing_correction",
      type: "dichotomous",
      text: "Are you wearing your glasses/contacts right now?",
      options: [
        { label: "Yes", marker: "yes" },
        { label: "No", marker: "no" }
      ],
      required: true,
      condition: {
        question_id: "vision_correction",
        operator: "eq",
        value: "yes"
      }
    }
  ]
}

Validated Psychological Scale (Simplified GAD-7)

{
  title: "Generalized Anxiety Disorder 7-Item Scale (GAD-7)",
  questions: [
    {
      id: "gad1",
      type: "scale",
      text: "Over the last 2 weeks, how often have you been bothered by: Feeling nervous, anxious, or on edge",
      scale_labels: ["Not at all", "Several days", "More than half the days", "Nearly every day"],
      required: true
    },
    {
      id: "gad2",
      type: "scale",
      text: "Over the last 2 weeks, how often have you been bothered by: Not being able to stop or control worrying",
      scale_labels: ["Not at all", "Several days", "More than half the days", "Nearly every day"],
      required: true
    }
    // ... remaining GAD-7 items
  ]
}

Design Recommendations

Question Design

Clarity: Use simple, unambiguous language
Neutrality: Avoid leading or loaded questions
Single Concept: One question per item (avoid double-barreled)
Response Options: Mutually exclusive and exhaustive
Sensitive Topics: Include "Prefer not to answer" option

Scale Design

Odd vs. Even: Odd-numbered scales allow neutral midpoint; even force direction
Anchors: Label endpoints clearly; optionally label all points
Range: 5-7 points typical for Likert; 0-10 for pain/difficulty scales
Directionality: Keep direction consistent (high = more of construct)

Questionnaire Length

Completion Time: Aim for <10 minutes for non-clinical samples
Question Count: 15-30 questions typical; >50 risks fatigue
Pages: Break into 3-5 pages for better experience
Progress Bar: Helps completion rates, especially for longer surveys

Required vs. Optional

Demographics: Age, gender often required for analysis
Screening: Eligibility criteria must be required
Experience: Post-task ratings can be optional
Sensitive: Health, income often better as optional

Common Issues and Solutions

Issue	Solution
Low completion rates	Shorten questionnaire; make optional questions truly optional
Straight-lining (same answer repeated)	Reverse-code some items; include attention checks
Missing data on key variables	Make critical questions required with clear instructions
Response bias (social desirability)	Assure anonymity; use validated scales; consider forced-choice formats
Participants rush through	Add time stamps; flag suspiciously fast completions (<2s/question)
Confusion about scales	Provide clear anchors and examples

Validated Scales Integration

When using validated psychological scales:

Permission: Ensure you have rights to use the scale
Exact Wording: Use verbatim question and response option text
Scoring: Follow published scoring algorithms
Interpretation: Use published norms and cutoffs
Citation: Reference original scale development paper

Common Validated Scales:

Depression: PHQ-9, BDI-II, CES-D
Anxiety: GAD-7, STAI, BAI
Personality: Big Five Inventory (BFI), HEXACO
Cognitive Complaints: Cognitive Failures Questionnaire (CFQ)
Sleep: Pittsburgh Sleep Quality Index (PSQI)

Data Analysis Considerations

Quantitative:

Compute scale scores (sum, mean, or weighted)
Test internal consistency (Cronbach's α)
Correlate with behavioral measures
Group differences (t-tests, ANOVA)

Qualitative (Open-Ended):

Thematic analysis of text responses
Content coding
Word frequency/sentiment analysis

Missing Data:

Report missingness rates
Use appropriate imputation if necessary (mean, regression, multiple imputation)
Consider listwise vs. pairwise deletion

References

Questionnaires are general tools; references depend on specific scales used. For questionnaire design:

Krosnick, J. A., & Presser, S. (2010). Question and questionnaire design. In P. V. Marsden & J. D. Wright (Eds.), Handbook of Survey Research (2nd ed., pp. 263-313). Emerald Group Publishing.
DeVellis, R. F. (2016). Scale Development: Theory and Applications (4th ed.). SAGE Publications.

For specific validated scales, cite the original development paper (e.g., Spitzer et al., 2006 for GAD-7).

Overview​

Why Researchers Use This Task​

Current Implementation Status​

Configuration Parameters​

Questionnaire Structure​

Question Object Structure​

Question Types​

Presentation Parameters​

Meta-Translation Keys​

Data Output​

Markers and Responses​

Summary Artifacts​

Example Questionnaires​

Demographics Survey​

Post-Task Ratings​

Screening Questionnaire with Conditional Logic​

Validated Psychological Scale (Simplified GAD-7)​

Design Recommendations​

Question Design​

Scale Design​

Questionnaire Length​

Required vs. Optional​

Common Issues and Solutions​

Validated Scales Integration​

Data Analysis Considerations​

References​

See Also​