Survey

The survey modality is a PRISM extension for handling complex questionnaires. It treats surveys as rich data with detailed metadata, rather than simple phenotypic variables.

File Name Structure

Survey data files MUST follow this naming convention:

sub-<label>[_ses-<label>]_survey-<label>.tsv

Note: The legacy format _task-<label>_beh.tsv is also supported but deprecated.

Sidecar JSON (*_survey.json)

The survey sidecar defines the structure, content, and administrative metadata of the questionnaire.

Top-Level Objects

Object	Requirement	Description
Technical	REQUIRED	Platform and respondent details.
Study	REQUIRED	Instrument identification.
Metadata	REQUIRED	Schema and creation details.
*	OPTIONAL	Any other key is treated as a Question Item.

Technical Object Fields

Key	Requirement	Type	Description
StimulusType	REQUIRED	string	MUST be "Questionnaire".
FileFormat	REQUIRED	string	MUST be "tsv".
SoftwarePlatform	REQUIRED	string	Platform used (e.g., "LimeSurvey 5.0").
Language	REQUIRED	string	Language code (e.g., "en", "de-AT").
Respondent	REQUIRED	string	Who answered (e.g., "self", "parent").
ResponseType	RECOMMENDED	array	Input method (e.g., ["button"], ["slider"]).

Study Object Fields

Key	Requirement	Type	Description
TaskName	REQUIRED	string	Short identifier (e.g., "bdi").
OriginalName	REQUIRED	string	Full name (e.g., "Beck Depression Inventory").
Version	OPTIONAL	string	Instrument version.
Citation	OPTIONAL	string	Reference citation.

Question Item Fields

Any top-level key that is not one of the above objects is considered a question definition (e.g., "Q01", "item_1").

Key	Requirement	Type	Description
Description	REQUIRED	string	The exact text of the question presented.
Levels	OPTIONAL	object	Mapping of numeric values to text labels.
Units	OPTIONAL	string	Units (if applicable).
TermURL	OPTIONAL	string	URL to an ontology term.

Example Sidecar

{
  "Technical": {
    "StimulusType": "Questionnaire",
    "FileFormat": "tsv",
    "SoftwarePlatform": "LimeSurvey",
    "Language": "en",
    "Respondent": "self"
  },
  "Study": {
    "TaskName": "bdi",
    "OriginalName": "Beck Depression Inventory"
  },
  "Metadata": {
    "SchemaVersion": "1.0.0",
    "CreationDate": "2025-01-01"
  },
  "Q01": {
    "Description": "I feel sad",
    "Levels": {
      "0": "I do not feel sad.",
      "1": "I feel sad",
      "2": "I am sad all the time and I can't snap out of it.",
      "3": "I am so sad and unhappy that I can't stand it."
    }
  }
}